{ "openapi": "3.0.1", "info": { "title": "Facebook Marketplace Scraper with Prices & New-Listing Alerts", "description": "Search Facebook Marketplace by keyword, city, price, condition and age and get every listing as a row: price, town, posted time, sold flag, photos and the seller's description. Monitoring mode returns only new listings, for deal alerts, resale sourcing and price research.", "version": "0.2", "x-build-id": "1o6yryViqXAtsIS1x" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/s-r~facebook-marketplace-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-s-r-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/s-r~facebook-marketplace-scraper/runs": { "post": { "operationId": "runs-sync-s-r-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/s-r~facebook-marketplace-scraper/run-sync": { "post": { "operationId": "run-sync-s-r-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": { "searchKeyword": { "title": "Search keyword", "type": "string", "description": "What to search Marketplace for, exactly as you would type it into the site's search box. Leave empty when pasting a Marketplace search URL. Category browsing is currently unsupported." }, "keywords": { "title": "Extra keywords", "type": "array", "description": "Additional search terms. Every keyword is crossed with every location, so three keywords across two cities is six searches. Use this instead of running the Actor six times.", "items": { "type": "string" } }, "location": { "title": "Location", "type": "string", "description": "The Marketplace city to search, as the slug Facebook puts in the URL (amsterdam, london, nyc) or the numeric city id from that same URL. Marketplace is city-scoped: there is no country-wide or worldwide search." }, "locations": { "title": "Extra locations", "type": "array", "description": "Additional city slugs or city ids. Every location is crossed with every keyword, so two cities and three keywords is six searches, each of which is paged independently.", "items": { "type": "string" } }, "country": { "title": "Market country", "type": "string", "description": "ISO country code of the market the cities belong to, lowercase. Marketplace localizes what it serves to where the request comes from, so setting this is what makes an Amsterdam search return the Dutch feed with Dutch towns and euro prices." }, "startUrls": { "title": "Marketplace URLs", "type": "array", "description": "Paste Marketplace search URLs from your browser after selecting filters. Direct URLs take precedence over the search builder. Category pages without a usable search feed finish with an empty dataset and a collection error.", "items": { "type": "string" } }, "category": { "title": "Category", "type": "string", "description": "Existing Marketplace category slug, retained for compatibility and ignored when direct URLs are supplied. Category browsing is currently unsupported, including category pages with a keyword. Use keyword and city searches without category." }, "sort": { "title": "Sort order", "enum": [ "best_match", "newest", "price_asc", "price_desc", "distance_asc" ], "type": "string", "description": "How Facebook should order the results. Newest first is what you want for monitoring; price ascending and descending walk the same market from opposite ends and reach different listings.", "default": "best_match" }, "minPrice": { "title": "Minimum price", "minimum": 0, "type": "integer", "description": "Lower price bound in the market's own currency. Verified to apply: a search with a 400 floor came back with 400 as its cheapest row." }, "maxPrice": { "title": "Maximum price", "minimum": 0, "type": "integer", "description": "Upper price bound in the market's currency. Combine with the minimum to divide a search into price bands." }, "condition": { "title": "Condition", "type": "array", "description": "Restrict to the condition bands sellers pick when they post. Choosing more than one widens the search rather than narrowing it.", "items": { "type": "string", "enum": [ "new", "used_like_new", "used_good", "used_fair" ], "enumTitles": [ "New", "Used, like new", "Used, good", "Used, fair" ] } }, "daysSinceListed": { "title": "Listed within", "type": "integer", "description": "Only listings posted within this many days. Facebook supports exactly three windows, 1, 7 and 30, and rejects anything else." }, "availability": { "title": "Availability", "enum": [ "in_stock", "sold" ], "type": "string", "description": "Whether to read the live listings or the ones already marked sold. Sold listings are what you want for a price history; live ones are what you want for what is on the market now.", "default": "in_stock" }, "deliveryMethod": { "title": "Delivery method", "enum": [ "all", "local_pickup", "shipping" ], "type": "string", "description": "Restrict to listings the seller will ship, or to ones that are collection only. Shipping is rare in some markets, so this filter can legitimately return nothing.", "default": "all" }, "radiusKm": { "title": "Search radius in kilometres", "minimum": 1, "type": "integer", "description": "Passed to Facebook as the distance ring around the chosen city. Facebook did not honour it in testing: a 2 km ring and a 250 km ring returned the same towns, some of them 100 km away, because the query Facebook actually runs carries its own fixed radius. It is sent because you asked for it. Filter on the city field in the output if distance really matters." }, "exactMatch": { "title": "Exact keyword match", "type": "boolean", "description": "Ask Facebook to treat the keyword as an exact phrase rather than loosely. It reordered our results without obviously narrowing them, so treat it as a hint rather than a guarantee.", "default": false }, "listingDetails": { "title": "Fetch listing details", "type": "boolean", "description": "Open each listing's page to add the seller's description, category path, approximate coordinates and shipping information. Requests an extra page per listing; leave it off when the search row is enough.", "default": false }, "allPhotos": { "title": "All photos", "type": "boolean", "description": "Collect every photo on the listing instead of just the cover image. Requires listing details to be on, because the extra photos only exist on the listing's own page.", "default": false }, "maxPagesPerUrl": { "title": "Pages per search", "minimum": 1, "maximum": 40, "type": "integer", "description": "How deep to follow each search. Page one is the 24 listings the search page itself carries; every page after that adds about 24 more. Twenty-six requests against one Amsterdam search returned 573 distinct listings and Facebook was still offering more, so depth is a budget decision rather than a hard ceiling. Each page is one request, so this is the main thing that decides how long a run takes.", "default": 5 }, "maxListings": { "title": "Maximum listings", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Hard cap on rows written to the dataset, applied after every search has been paged. Leave room above the page size: one search page carries 24 listings and each extra page adds about 24 more.", "default": 100 }, "maxDetails": { "title": "Maximum detail fetches", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Cap on how many listings get their own page opened, so a wide search cannot turn into an unexpectedly large bill. Ignored when listing details are off." }, "onlyNewListings": { "title": "Only new listings (monitoring mode)", "type": "boolean", "description": "Return only the listings that have appeared since the last run of this same monitor. Schedule the Actor and every run gives you the new arrivals and nothing else. A run that finds nothing new succeeds with an empty dataset.", "default": false }, "cacheKey": { "title": "Monitor name", "type": "string", "description": "Names the memory that monitoring mode reads and writes, so two different saved searches do not share one list of already-seen listings. Pick any short label and keep using it for that search." }, "cacheStorageName": { "title": "Monitor storage name", "type": "string", "description": "The named key-value store that holds monitoring memory across runs. Leave it alone unless you want several monitors kept in separate stores; the run summary reports which store was actually used.", "default": "facebook-marketplace-seen" }, "retries": { "title": "Retries per page", "minimum": 1, "maximum": 8, "type": "integer", "description": "How many times to re-request a page that came back without listings on it. Facebook serves a signed-out visitor an empty shell for roughly one request in six, and that shell is indistinguishable from a search with no results unless you ask again.", "default": 4 } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }