{
  "openapi": "3.0.1",
  "info": {
    "title": "Craigslist Listings Scraper - Search, Prices & Details",
    "description": "Search Craigslist across many cities in one run. Every listing as a clean row: title, price, photos, neighbourhood, GPS and post date, plus the full description on demand.",
    "version": "1.0",
    "x-build-id": "Z0gDj2MiqpyfTaYFS"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sian.agency~craigslist-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sian.agency-craigslist-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/sian.agency~craigslist-scraper/runs": {
      "post": {
        "operationId": "runs-sync-sian.agency-craigslist-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/sian.agency~craigslist-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-sian.agency-craigslist-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "operation": {
            "title": "🎯 What do you want to scrape?",
            "enum": [
              "search",
              "detail"
            ],
            "type": "string",
            "description": "🎯 **PICK ONE PER RUN.**\n\n🔍 **Listing Search** — every listing in a city and section that matches your filters. This is the one you want 95% of the time.\n\n📄 **Listing Detail** — you already have posting URLs and want the full description, the attribute table and every photo for each one.\n\n💡 Want descriptions on a SEARCH run instead? Leave this on Listing Search and switch on **Fetch full descriptions** below.",
            "default": "search"
          },
          "cities": {
            "title": "🏙️ Craigslist cities",
            "type": "array",
            "description": "🏙️ **WHERE TO SEARCH.** Use the site subdomain, one per line: `newyork`, `losangeles`, `sfbay`, `chicago`, `toronto`, `london`, `berlin`.\n\n🌍 **Every Craigslist site on earth works** — the area is resolved from the site itself.\n\n🚀 **This is the feature Craigslist does not have.** One search on craigslist.org covers ONE city and stops at ~2,880 results. List ten cities here and you get all ten in one run.\n\n💡 The subdomain is in the address bar: `newyork`.craigslist.org.",
            "default": [
              "newyork"
            ],
            "items": {
              "type": "string"
            }
          },
          "category": {
            "title": "🗂️ Category",
            "enum": [
              "sss",
              "cta",
              "apa",
              "rea",
              "hhh",
              "jjj",
              "ggg",
              "bbb",
              "ccc",
              "fua",
              "ela",
              "sya",
              "zip"
            ],
            "type": "string",
            "description": "🗂️ **WHICH SECTION** of Craigslist to search.\n\n🛍️ **For sale (all)** covers every for-sale sub-category at once — the widest net.\n\n🎯 Narrow sections return richer rows: **Cars & trucks** adds the odometer reading, **Apartments** adds bedrooms and square footage, **Jobs** and **Gigs** add the pay line.\n\n💡 Searching a keyword across everything? Leave it on For sale (all).",
            "default": "sss"
          },
          "query": {
            "title": "🔑 Search keyword",
            "type": "string",
            "description": "🔑 **WHAT TO LOOK FOR** — the same words you would type into Craigslist's own search box.\n\n⬜ **Leave it empty to take the whole section** for each city. That is the fastest way to build a full local dataset.\n\n🎯 Craigslist matches the title and the body, so `bike` also finds \"mountain bike frame\".\n\n💡 One keyword per run. To sweep several, schedule one run per keyword — each is billed only for the rows it returns.",
            "default": "bike"
          },
          "maxResults": {
            "title": "🔢 Max listings",
            "minimum": 1,
            "maximum": 20000,
            "type": "integer",
            "description": "🔢 **STOP AFTER THIS MANY LISTINGS**, counted across every city in the run.\n\n📦 Listings arrive 360 at a time, so the run finishes the batch it is on and then stops. You may receive a few more than you asked for, and you are only charged for rows delivered.\n\n💰 **Free accounts are capped at 25 rows per run** whatever you type here. Paid accounts are not.\n\n⚠️ Craigslist itself serves at most ~2,880 rows per city per search. One page is 360 listings, so budgets under 360 only read the first city.",
            "default": 500
          },
          "includeDetails": {
            "title": "📄 Fetch full descriptions (extra charge)",
            "type": "boolean",
            "description": "📄 **THE WHOLE POSTING, NOT ONLY THE CARD.** Adds the complete description, the seller's attribute table (condition, make, model, bedrooms, laundry — whatever the section uses) and the full photo set.\n\n💰 **Charged per enriched listing** on top of the search row. Leave it off and you pay search rows only.\n\n🎯 **Worth it for:** lead generation and resale sourcing.\n❌ **Skip it for:** price tracking, since the card already carries the price.",
            "default": false
          },
          "listingUrls": {
            "title": "🔗 Posting URLs",
            "uniqueItems": true,
            "type": "array",
            "description": "🔗 **FOR LISTING DETAIL MODE:** the Craigslist postings you want expanded.\n\n📱 Open the posting → copy the address bar. Both forms work: `craigslist.org/view/d/<slug>/<token>` and the older `city.craigslist.org/.../123456789.html`.\n\n📝 **Bulk edit** — one URL per line. 📁 **Upload a .txt file**. 🔗 **+ Add** — one at a time.\n\n⚠️ A bare posting ID is not enough: the link carries a token the ID does not.\n\n💰 **Free accounts: 25 postings per run. Paid: unlimited.**",
            "default": [],
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "searchUrls": {
            "title": "🌐 Search URLs",
            "uniqueItems": true,
            "type": "array",
            "description": "🌐 **PASTE A CRAIGSLIST SEARCH INSTEAD OF FILLING THE FORM.** Set the filters on craigslist.org, copy the address bar, drop it here.\n\n🎛️ **Every filter in that URL is honoured** — keyword, price band, radius, sort, and the section-specific ones the form above does not expose (bedrooms, make and model, wheel size, employment type).\n\n➕ Search URLs are searched **in addition to** the cities above.\n\n💡 This is the power-user path: anything Craigslist's own search can express, this can run.",
            "default": [],
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "minPrice": {
            "title": "💵 Min price",
            "minimum": 0,
            "type": "integer",
            "description": "💵 **CHEAPEST LISTING TO INCLUDE**, in the city's own currency.\n\n⬜ **0 means no lower bound** — that is the default.\n\n🎯 Filtering happens at Craigslist, so a price band makes the run faster and cheaper: you are not billed for rows you filtered out.\n\n⚠️ Sections without prices (jobs, gigs, community) ignore this.",
            "default": 0
          },
          "maxPrice": {
            "title": "💰 Max price",
            "minimum": 0,
            "type": "integer",
            "description": "💰 **MOST EXPENSIVE LISTING TO INCLUDE**, in the city's own currency.\n\n⬜ **0 means no upper bound** — that is the default.\n\n🎯 Pair it with Min price to sweep one price band at a time. That is also how you get past the ~2,880-row ceiling on a big city: run $0-500, then $500-1000, and so on.",
            "default": 0
          },
          "sellerType": {
            "title": "🧑‍💼 Sold by",
            "enum": [
              "all",
              "owner",
              "dealer"
            ],
            "type": "string",
            "description": "🧑‍💼 **PRIVATE SELLERS OR DEALERS.**\n\n🧑 **Owner only** is the lead-generation filter: private sellers and landlords with no agent between you and them.\n\n🏪 **Dealer only** is the competitive-intelligence filter: professional inventory, priced daily.\n\n⚠️ Applies to for-sale, vehicle and housing sections. Jobs and gigs ignore it.",
            "default": "all"
          },
          "hasImage": {
            "title": "🖼️ Only with photos",
            "type": "boolean",
            "description": "🖼️ **SKIP LISTINGS WITH NO PHOTO.**\n\n🎯 On Craigslist a missing photo usually means a low-effort or stale post, so this is the cheapest quality filter there is.\n\n📸 Rows carry every photo URL at 600x450, ready to display or download.\n\n💡 Essential for resale sourcing and property leads; leave it off when counting the whole market.",
            "default": false
          },
          "postedToday": {
            "title": "🆕 Posted today only",
            "type": "boolean",
            "description": "🆕 **ONLY WHAT WENT UP TODAY.**\n\n⏰ **This is the scheduling switch.** Run the actor daily with this on and you pay for the new listings only, instead of re-buying the whole market every morning.\n\n🎯 Gets you to FSBO, rentals and underpriced resale stock first: the good ones are gone within hours.\n\n💡 Pair it with Sort by newest first.",
            "default": false
          },
          "hideDuplicates": {
            "title": "♻️ Hide duplicates",
            "type": "boolean",
            "description": "♻️ **COLLAPSE REPOSTS OF THE SAME ITEM.**\n\n🚗 Dealers and landlords repost the same unit every few days to stay at the top of the list, so vehicle and housing searches are full of near-identical rows.\n\n🎯 On for a clean count of what is actually for sale. Off if you are studying reposting behaviour itself.",
            "default": false
          },
          "postalCode": {
            "title": "📮 ZIP / postal code",
            "type": "string",
            "description": "📮 **CENTRE THE SEARCH ON A POSTAL CODE** instead of the whole city.\n\n📏 **Needs Search radius below** to do anything: a postal code with no radius is ignored.\n\n🎯 A metro like New York or Los Angeles covers a huge area; this is how you keep the results inside the neighbourhood you actually work in.",
            "default": ""
          },
          "searchDistance": {
            "title": "📏 Search radius (miles)",
            "minimum": 0,
            "maximum": 500,
            "type": "integer",
            "description": "📏 **HOW FAR FROM THE POSTAL CODE** to look, in miles.\n\n⬜ **0 searches the whole city** — the default.\n\n🎯 5-10 miles for one neighbourhood, 25 for a metro, 100+ to pull in the surrounding towns a single city site does not cover.",
            "default": 0
          },
          "sort": {
            "title": "↕️ Sort by",
            "enum": [
              "date",
              "dateoldest",
              "rel",
              "priceasc",
              "pricedsc"
            ],
            "type": "string",
            "description": "↕️ **WHICH LISTINGS COME FIRST** — and, when you cap the run, which ones you actually get.\n\n🕒 **Newest first** for monitoring and lead generation.\n🎯 **Most relevant** for a one-off keyword sweep.\n⬆️ **Cheapest first** for bargain hunting and resale sourcing.\n\n💡 With Max listings set, sorting decides the sample you take.",
            "default": "date"
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}