{ "openapi": "3.0.1", "info": { "title": "Facebook Marketplace Scraper", "description": "Scrape Facebook Marketplace listings by location, category, and filters. Extract titles, prices, images, descriptions, seller info, and posting time. Ideal for market research, price tracking, and lead generation.", "version": "0.0", "x-build-id": "YgAjCIi5njXEyDyB1" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/calm_builder~facebook-marketplace-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-calm_builder-facebook-marketplace-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/calm_builder~facebook-marketplace-scraper/runs": { "post": { "operationId": "runs-sync-calm_builder-facebook-marketplace-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/calm_builder~facebook-marketplace-scraper/run-sync": { "post": { "operationId": "run-sync-calm_builder-facebook-marketplace-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": { "startUrls": { "title": "Marketplace search URLs", "type": "array", "description": "One Marketplace **search or category** URL per row, scraped **exactly as provided**.\n\nGlobal and `vehicle*` filters are **ignored** here. Never silently drop requested filtering: either use `keywordSearches`/`vehicleSearches` instead (preferred), or encode it in the URL query string — `&minPrice=100&maxPrice=300`, `&daysSinceListed=1`, `&itemCondition=used_good`, `&sortBy=creation_time_descend`.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "itemUrls": { "title": "Marketplace item URLs", "type": "array", "description": "One Facebook Marketplace **listing page** URL per row (`/marketplace/item/...`). Each link is scraped as-is and always returns full listing details.\n\n**Important:** global filters and `vehicle*` filters are **ignored** here, and `maxListings` does **not** apply — each URL produces exactly one listing. The detail page is **always** fetched, so each successful listing is billed as a **listing detail** event. Use this field only when you already know the specific listings you want.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "keywordSearches": { "title": "Query and location", "type": "array", "description": "One row per keyword search (**query** + **location slug**). Preferred mode for general items — filters apply to rows built here.\n\n**Coverage:** each row reaches only ~**65 km** around one city; a city does not cover its metro area. For wider coverage add **multiple rows**, same query, nearby slugs (`toronto`, `mississauga`, `oshawa`), and set `deduplicateListings: true`.\n\nEach row counts as one search for `maxListings`.", "items": { "type": "object", "properties": { "query": { "title": "Search query", "type": "string", "description": "Keyword or phrase to search for, e.g. `iphone 13`, `sectional sofa`, `2020 honda civic`.", "minLength": 1 }, "locationSlug": { "title": "Location slug", "type": "string", "description": "Marketplace city slug — the city segment of a Facebook Marketplace URL, lowercase (`montreal` → `facebook.com/marketplace/montreal/search`; also `sanfrancisco`, `newyork`, `toronto`). Use the city slug only: no country, province, or state names, no spaces, and no display names like `San Francisco`.\n\nCovers roughly a **65 km** radius around that city. For a wider area, add more rows with nearby city slugs rather than expecting one slug to cover a region.", "minLength": 1, "pattern": "^[a-z0-9-]+$" } }, "required": [ "query", "locationSlug" ] } }, "vehicleSearches": { "title": "Make and location", "type": "array", "description": "One row per vehicle search (**make** + **location slug**). Use for cars and trucks, not `keywordSearches` — only these rows accept the `vehicle*` filters.\n\n**Coverage:** each row reaches ~**65 km** around one city. For wider coverage add **multiple rows**, same make, nearby slugs, plus `deduplicateListings: true`. Each row is one search for `maxListings`.\n\n**Make holds only at the default `sortBy`.** With any other sort, expect other makes and filter them out downstream.", "items": { "type": "object", "properties": { "make": { "title": "Make", "type": "string", "description": "Vehicle manufacturer. Choose **All** to include every make for this location.", "editor": "select", "default": "all", "enum": [ "all", "acura", "alfa_romeo", "aston_martin", "audi", "bmw", "bentley", "buick", "coda", "cadillac", "chevrolet", "chrysler", "daewoo", "daihatsu", "dodge", "eagle", "ferrari", "fiat", "fisker", "ford", "freightliner", "gmc", "genesis", "geo", "honda", "hummer", "hyundai", "infiniti", "isuzu", "jaguar", "jeep", "kia", "lamborghini", "land_rover", "lexus", "lincoln", "lotus", "lucid", "mini", "maserati", "maybach", "mazda", "mclaren", "mercedes_benz", "mercury", "mitsubishi", "nissan", "oldsmobile", "panoz", "plymouth", "polestar", "pontiac", "porsche", "ram", "rivian", "rolls_royce", "srt", "saab", "saturn", "scion", "smart", "subaru", "suzuki", "tesla", "toyota", "volkswagen", "volvo" ], "enumTitles": [ "All", "Acura", "Alfa Romeo", "Aston Martin", "Audi", "BMW", "Bentley", "Buick", "CODA", "Cadillac", "Chevrolet", "Chrysler", "Daewoo", "Daihatsu", "Dodge", "Eagle", "Ferrari", "Fiat", "Fisker", "Ford", "Freightliner", "GMC", "Genesis", "Geo", "Honda", "Hummer", "Hyundai", "Infiniti", "Isuzu", "Jaguar", "Jeep", "Kia", "Lamborghini", "Land Rover", "Lexus", "Lincoln", "Lotus", "Lucid", "MINI", "Maserati", "Maybach", "Mazda", "Mclaren", "Mercedes-Benz", "Mercury", "Mitsubishi", "Nissan", "Oldsmobile", "Panoz", "Plymouth", "Polestar", "Pontiac", "Porsche", "Ram", "Rivian", "Rolls-Royce", "SRT", "Saab", "Saturn", "Scion", "Smart", "Subaru", "Suzuki", "Tesla", "Toyota", "Volkswagen", "Volvo" ] }, "locationSlug": { "title": "Location slug", "type": "string", "description": "Marketplace city slug — the city segment of a Facebook Marketplace URL, lowercase (`montreal` → `facebook.com/marketplace/montreal/vehicles`; also `sanfrancisco`, `newyork`, `toronto`). Use the city slug only: no country, province, or state names, no spaces, and no display names like `San Francisco`.\n\nCovers roughly a **65 km** radius around that city. For a wider area, add more rows with nearby city slugs rather than expecting one slug to cover a region.", "minLength": 1, "pattern": "^[a-z0-9-]+$" } }, "required": [ "locationSlug" ] } }, "vehicleMinYear": { "title": "Minimum year", "minimum": 1900, "maximum": 2030, "type": "integer", "description": "Earliest model year to include. Leave empty for no minimum.\n\nIf both min and max year are set, min must be ≤ max; invalid pairs are skipped at runtime.\n\nApplies to `vehicleSearches` rows only — **ignored** for `keywordSearches`, `startUrls`, and `itemUrls`." }, "vehicleMaxYear": { "title": "Maximum year", "minimum": 1900, "maximum": 2030, "type": "integer", "description": "Latest model year to include. Leave empty for no maximum.\n\nIf both min and max year are set, min must be ≤ max; invalid pairs are skipped at runtime.\n\nApplies to `vehicleSearches` rows only — **ignored** for `keywordSearches`, `startUrls`, and `itemUrls`." }, "vehicleBodyStyles": { "title": "Body style", "uniqueItems": true, "type": "array", "description": "Filter by body style. Leave empty to include all body styles.\n\nApplies to `vehicleSearches` rows only — **ignored** for `keywordSearches`, `startUrls`, and `itemUrls`.", "items": { "type": "string", "enum": [ "convertible", "coupe", "hatchback", "minivan", "sedan", "station_wagon", "suv", "truck", "small_car", "other" ], "enumTitles": [ "Convertible", "Coupe", "Hatchback", "Minivan", "Sedan", "Station wagon", "SUV", "Truck", "Small Car", "Other" ] } }, "vehicleMinMileage": { "title": "Minimum mileage", "minimum": 0, "type": "integer", "description": "Minimum odometer reading. Units follow the local Marketplace listing format. Leave empty for no minimum.\n\nIf both min and max mileage are set, min must be ≤ max; invalid pairs are skipped at runtime.\n\nApplies to `vehicleSearches` rows only — **ignored** for `keywordSearches`, `startUrls`, and `itemUrls`." }, "vehicleMaxMileage": { "title": "Maximum mileage", "minimum": 0, "type": "integer", "description": "Maximum odometer reading. Units follow the local Marketplace listing format. Leave empty for no maximum.\n\nIf both min and max mileage are set, min must be ≤ max; invalid pairs are skipped at runtime.\n\nApplies to `vehicleSearches` rows only — **ignored** for `keywordSearches`, `startUrls`, and `itemUrls`." }, "vehicleTransmission": { "title": "Transmission", "enum": [ "all", "automatic", "manual" ], "type": "string", "description": "Filter by transmission type.\n\nApplies to `vehicleSearches` rows only — **ignored** for `keywordSearches`, `startUrls`, and `itemUrls`.", "default": "all" }, "sortBy": { "title": "Sort", "enum": [ "best_match", "price_ascend", "price_descend", "creation_time_descend", "creation_time_ascend", "distance_ascend", "distance_descend", "vehicle_mileage_ascend", "vehicle_mileage_descend", "vehicle_year_descend", "vehicle_year_ascend" ], "type": "string", "description": "Result order for built searches. **Suggested** adds no sort parameter. Options marked *(vehicles only)* apply to `vehicleSearches` rows only.\n\nApplies to `keywordSearches` and `vehicleSearches` rows only — **ignored** for `startUrls` and `itemUrls`.\n\n**Vehicle searches:** any sort other than **Suggested** makes Facebook return other makes too. Keep **Suggested** when the make must hold.", "default": "best_match" }, "exactMatch": { "title": "Exact match", "type": "boolean", "description": "When enabled, Facebook matches the search query more strictly (`exact=true`). When disabled, broader matching is used (`exact=false`).\n\nApplies to `keywordSearches` and `vehicleSearches` rows only — **ignored** for `startUrls` and `itemUrls`.", "default": false }, "minPrice": { "title": "Minimum price", "minimum": 0, "type": "integer", "description": "Minimum price in the local Marketplace currency. Leave empty for no minimum.\n\nIf both min and max are set, min must be ≤ max; invalid pairs are skipped at runtime.\n\nApplies to `keywordSearches` and `vehicleSearches` rows only — **ignored** for `startUrls` and `itemUrls`." }, "maxPrice": { "title": "Maximum price", "minimum": 0, "type": "integer", "description": "Maximum price in the local Marketplace currency. Leave empty for no maximum.\n\nIf both min and max are set, min must be ≤ max; invalid pairs are skipped at runtime.\n\nApplies to `keywordSearches` and `vehicleSearches` rows only — **ignored** for `startUrls` and `itemUrls`." }, "conditions": { "title": "Condition", "uniqueItems": true, "type": "array", "description": "Filter by item condition. Leave empty to include all conditions.\n\nApplies to `keywordSearches` and `vehicleSearches` rows only — **ignored** for `startUrls` and `itemUrls`.", "items": { "type": "string", "enum": [ "new", "used_like_new", "used_good", "used_fair" ], "enumTitles": [ "New", "Used – like new", "Used – good", "Used – fair" ] } }, "dateListed": { "title": "Date listed", "enum": [ "all", "last_24_hours", "last_7_days", "last_30_days" ], "type": "string", "description": "Only include listings posted within the selected time window.\n\nApplies to `keywordSearches` and `vehicleSearches` rows only — **ignored** for `startUrls` and `itemUrls`.", "default": "all" }, "availability": { "title": "Availability", "enum": [ "available", "sold" ], "type": "string", "description": "Filter by whether listings are still available or already sold. Defaults to `available`; set to `sold` only when the user explicitly wants sold or historical listings.\n\nApplies to `keywordSearches` and `vehicleSearches` rows only — **ignored** for `startUrls` and `itemUrls`.", "default": "available" }, "maxListings": { "title": "Maximum listings per search", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap per Direct Search URL or per built search row (each keyword/vehicle row is one search). Does **not** apply to Direct item URLs.\n\n**Main cost control.** Total = this value × number of searches, so 5 rows at 100 is 500 listings. Keep the default 10 for exploratory questions; raise it only when breadth is genuinely required. **Never pair a large value with `fetchDetails: true`** — the most expensive way to run this Actor.", "default": 10 }, "fetchDetails": { "title": "Fetch detailed information", "type": "boolean", "description": "Visit each listing page for richer fields (description, seller, extra metadata). Slower, more complete.\n\n**Cost:** every fetched listing bills a **listing detail** event, scaling with `maxListings` × searches. Leave `false` for discovery or price surveys. Enable only when descriptions or seller data are genuinely needed, and then keep `maxListings` small (10–20). Large `maxListings` plus this is almost never wanted.", "default": false }, "deduplicateListings": { "title": "Deduplicate listings across searches", "type": "boolean", "description": "When enabled, each listing is saved to the dataset **at most once**, even if it appears in multiple search results. The first search (or direct item URL) that reaches the listing sets its `sourceUrl` in the output.\n\nPer-search caps still apply: skipped duplicates do not count toward **Maximum listings per search**, so overlapping searches can keep paginating until each reaches its cap or runs out of results.", "default": false } } }, "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 } } } } } } } } } }