{ "openapi": "3.0.1", "info": { "title": "Facebook Marketplace | Search | Detail Pages | Scraper", "description": "Scrape Facebook Marketplace for price tracking, reselling & car-dealer research. Keyword or URL search, no cookies or login. Filter by price, condition & location radius. Cars return make, model, odometer, transmission & VIN. Photos, seller & GPS per listing. JSON or CSV out.", "version": "0.0", "x-build-id": "AerPsSogHGYy8YChc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/memo23~facebook-marketplace-cheerio/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-memo23-facebook-marketplace-cheerio", "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/memo23~facebook-marketplace-cheerio/runs": { "post": { "operationId": "runs-sync-memo23-facebook-marketplace-cheerio", "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/memo23~facebook-marketplace-cheerio/run-sync": { "post": { "operationId": "run-sync-memo23-facebook-marketplace-cheerio", "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": "URLs of the Marketplace search pages to scrape", "type": "array", "description": "Paste one or more Facebook Marketplace URLs such as `'https://www.facebook.com/marketplace/nyc/search/?query=sleeper%20trucks'`.", "items": { "type": "string" } }, "searchQuery": { "title": "Keyword to search", "type": "string", "description": "Search term to use when building a Marketplace search URL." }, "sortBy": { "title": "Sort By", "enum": [ "best_match", "creation_time_descend", "price_ascend", "price_descend", "distance_ascend" ], "type": "string", "description": "Sort order used when building the Marketplace search.", "default": "best_match" }, "daysSinceListed": { "title": "Days Since Listed", "enum": [ "0", "1", "7", "30" ], "type": "string", "description": "Preset age filter matching the reference repo. Keeps only listings posted within the last N days: `\"0\"` = any time (default), `\"1\"` = last 24 hours, `\"7\"` = last 7 days, `\"30\"` = last 30 days.", "default": "0" }, "availability": { "title": "Availability", "enum": [ "in stock", "out of stock" ], "type": "string", "description": "Availability filter used when building the Marketplace search.", "default": "in stock" }, "deliveryMethod": { "title": "Delivery", "enum": [ "all", "local_pick_up", "shipping" ], "type": "string", "description": "Delivery filter used when building the Marketplace search.", "default": "all" }, "conditionNew": { "title": "Condition: New", "type": "boolean", "description": "Include new items in the generated Marketplace URL.", "default": false }, "conditionUsedLikeNew": { "title": "Condition: Used - like new", "type": "boolean", "description": "Include used-like-new items in the generated Marketplace URL.", "default": false }, "conditionUsedGood": { "title": "Condition: Used - good", "type": "boolean", "description": "Include used-good items in the generated Marketplace URL.", "default": false }, "conditionUsedFair": { "title": "Condition: Used - fair", "type": "boolean", "description": "Include used-fair items in the generated Marketplace URL.", "default": false }, "minPrice": { "title": "Min. Price", "type": "integer", "description": "Minimum listing price for the generated Marketplace URL.", "default": 0 }, "maxPrice": { "title": "Max. Price", "type": "integer", "description": "Maximum listing price for the generated Marketplace URL.", "default": 0 }, "countryPreset": { "title": "Country preset", "enum": [ "", "usa", "usa_full", "can", "mex", "bra", "arg", "aus", "nzl", "ind", "gbr", "fra", "spa", "usa_metros", "can_full", "mex_full", "bra_full", "arg_full", "aus_full", "nzl_full", "ind_full", "gbr_full", "fra_full", "spa_full" ], "type": "string", "description": "Optional multi-city preset. Each preset expands into a fixed list of Marketplace locations in that country, and EACH location is a separate start URL - so a preset with 128 locations costs roughly 128x the start fee of a single-location run. Pick the smallest preset that covers what you need. Every location in the expanded ('verified') presets was checked against Facebook and confirmed to resolve to the right place. Leave empty to use a single Marketplace location below.", "default": "" }, "marketplaceLocation": { "title": "Marketplace location", "type": "string", "description": "Marketplace location: a slug such as `phoenix` or `nyc`, a Facebook page id, or a place written as `City, State, Country` (for example `Los Angeles, California, United States`). The city is what gets searched, and a few cities use Facebook's own short token (`la`, `nyc`). Used for a single generated URL when no country preset is selected. When Location is also filled in, this field is the one that is searched." }, "location": { "title": "Location", "type": "string", "description": "Same as Marketplace location, for callers that send a place as `City, State, Country`. Used only when Marketplace location is empty." }, "radiusKm": { "title": "Search radius (km)", "type": "integer", "description": "Search radius in kilometres. Facebook's logged-out search ignores this value (a 5 km request and an 805 km request return the same listings), so it does not narrow what Facebook sends. Turn on Precise location to drop listings whose own coordinates fall outside this radius. Listings that publish no coordinates are kept. To cover a wider area, add more locations or pick a bigger country preset.", "default": 200 }, "exact": { "title": "Exact search", "type": "boolean", "description": "If checked, Facebook will try to match the search query more exactly when the generated URL is used.", "default": false }, "categories": { "title": "Categories", "type": "array", "description": "Pick one or more Facebook Marketplace categories. Each selected category is scraped as its own search (Facebook only accepts one category per search), and the results are combined. Leave empty to search all categories. If you also use a Country preset, every city is searched for every selected category.", "items": { "type": "string", "enum": [ "vehicles", "propertyforsale", "propertyrentals", "apparel", "electronics", "entertainment", "family", "free", "garden", "hobbies", "home", "instruments", "pets", "sports", "toys", "classifieds" ], "enumTitles": [ "Vehicles", "Home Sales (Property for sale)", "Property Rentals", "Apparel", "Electronics", "Entertainment", "Family", "Free Stuff", "Garden & Outdoor", "Hobbies", "Home Goods", "Musical Instruments", "Pet Supplies", "Sporting Goods", "Toys & Games", "Classifieds" ] } }, "categoryId": { "title": "Category ID (advanced)", "type": "string", "description": "Advanced: raw Facebook Marketplace category slug(s) to append as `category_id`. Prefer the Categories picker above. You can list several slugs comma-separated (e.g. `vehicles,electronics`) and each is scraped as its own search. Use category slugs like `vehicles` or `propertyforsale`, not numeric IDs." }, "latitude": { "title": "Latitude", "type": "number", "description": "Optional latitude for precise pinned-location searches. Provide longitude too." }, "longitude": { "title": "Longitude", "type": "number", "description": "Optional longitude for precise pinned-location searches. Provide latitude too." }, "includeSeller": { "title": "Fetch each listing page (full description, all photos, attributes)", "type": "boolean", "description": "If checked, the scraper opens each listing's own page and adds the full description, all photos, structured attributes, precise location and (for vehicles) the complete `vehicle` field set. This is the only way to get the description: Facebook's search feed does not carry it. Charged as one detail-enrichment event per listing on top of the result price. The seller's name/profile is served by Facebook only to logged-in sessions — provide `cookies` to get it; without cookies `seller` stays null but `vehicle.sellerType` is still returned. Default: false (faster, search-results-only runs).", "default": false }, "mustMentionKeywords": { "title": "Keep only listings that mention", "type": "array", "description": "Words a listing must mention to be delivered, for example `comic`, `marvel`, `manga`, `graphic novel`. A listing is kept when its title or its description contains one of them. The title is checked first; when it has none of the words and Fetch each listing page is on, the description decides, so a listing that names the item only in its description is kept. With Fetch each listing page off, only the title is checked. Matching ignores case and accents and matches the start of a word, so `comic` also catches `comics`. Listings that fail are dropped before delivery and not charged. Leave empty to keep everything Facebook returns.", "items": { "type": "string" } }, "excludeKeywords": { "title": "Drop listings whose title mentions", "type": "array", "description": "Words that rule a listing out by its title, for example `costume`, `shirt`, `poster`. A listing is dropped, before its page is opened and without charge, when its title contains one of these words and none of the words in Keep only listings that mention. So `Funko variant comic #1` stays with `funko` here, while `Funko Pop Batman figure` is dropped. Same matching rules as above.", "items": { "type": "string" } }, "flattenOutput": { "title": "Flatten output for easier use", "type": "boolean", "description": "If checked, the actor will export a cleaner, flatter dataset with top-level fields like title, description, location, and pricing. Leave it off to keep the current response format for existing integrations.", "default": false }, "monitoringMode": { "title": "Run in monitoring mode: only listings new since previous runs are scraped", "type": "boolean", "description": "If checked, only listings not delivered in previous runs are scraped. Each run stops paging after a stretch of already-seen pages sized to maxItems, so it does not re-read the whole feed. For a strictly newest-first feed set Sort by to creation_time_descend. On the pay-per-event version, runs from a free Apify plan cannot use monitoring mode: such a run stops before scraping and only the start fee is charged.", "default": false }, "maxListingAgeHours": { "title": "Max listing age (hours)", "minimum": 0, "type": "integer", "description": "Deliver only listings created within the last N hours — older ones are dropped before delivery and never billed. Pagination stops once the feed is past the age window. Works best with sortBy=creation_time_descend in the URL and monitoring mode. 0 = no explicit cutoff; a `daysSinceListed` filter in the URL (or the Days Since Listed input) then sets one automatically at the window plus one day (48 h for 1 day), because Facebook counts calendar days and its first page does not always honour that filter.", "default": 0 }, "untilDate": { "title": "Until date", "type": "string", "description": "Keep listings created on or after this date, written YYYY-MM-DD (UTC). Older listings are dropped before delivery and not billed. When Max listing age is also set, the tighter of the two applies. Listings with no creation time are kept." }, "cacheStorageId": { "title": "Monitoring cache id", "type": "string", "description": "Separate seen-listing memory for this monitor. Leave empty to keep using the shared store (`facebook-marketplace-default-filter-ppe`), which is what existing schedules already write to. Set a short name such as `cars-phoenix` when two monitors in the same account must not hide each other's listings. Has effect when Monitoring mode is on." }, "resetMonitoringCache": { "title": "Reset monitoring cache before this run", "type": "boolean", "description": "If checked, the actor will wipe this run's monitoring cache (the store named by Monitoring cache id, or `facebook-marketplace-default-filter-ppe` when that is empty) at the start of this run. All currently-live listings will then be treated as new and pushed to the dataset. Use this once when switching from testing to production, then turn it off so subsequent runs only return genuinely new items. Has no effect when `monitoringMode` is off.", "default": false }, "preciseLocation": { "title": "Precise location filtering", "type": "boolean", "description": "If checked, the scraper will enforce strict geo-filtering. It will use latitude/longitude from the URL (e.g. &latitude=39.04&longitude=-77.49&radius=65) instead of coordinates inferred by Facebook from the proxy IP. Results whose location falls outside the requested radius will be discarded. Recommended when Facebook redirects away from the city slug and returns listings from the wrong region.", "default": false }, "locationResultsMode": { "title": "How should location be handled?", "enum": [ "maximize_results", "mark_far_results", "only_nearby_results" ], "type": "string", "description": "Choose whether to keep as many Facebook results as possible, keep them but mark far-away ones, or only keep listings that fall inside the resolved search radius after checking item detail pages.", "default": "maximize_results" }, "cookies": { "title": "Facebook cookies — optional, only for seller identity", "type": "array", "description": "OPTIONAL. Every listing field — photos, description, location, price, dates and vehicle data — is returned without cookies. Supply them only to populate `marketplace_listing_seller`: Facebook stopped exposing seller identity to logged-out sessions, so with `includeSeller` on and no cookies that one field comes back empty and the run says so in the log. Export with a browser extension such as EditThisCookie; they are sanitised and reused for both URL-based and filter-generated searches." }, "maxItems": { "title": "Maximum items per crawl", "type": "integer", "description": "Maximum listings to scrape PER START URL (each URL gets its own budget — 12 URLs with maxItems 72 can return up to 864 items). In filter mode (no start URLs) it is simply the run's total. The run never exceeds your maximum cost per run setting. On the pay-per-event version, runs from a free Apify plan are limited to 1 start URL and 60 results.", "default": 100 }, "minDelay": { "title": "Min delay for API call", "type": "integer", "description": "Minimum delay in seconds between Facebook API calls. Lower = faster and cheaper runs; raise it if you see rate-limiting on very large runs.", "default": 2 }, "maxDelay": { "title": "Max delay for API call", "type": "integer", "description": "Maximum delay in seconds between Facebook API calls. Lower = faster and cheaper runs; raise it if you see rate-limiting on very large runs.", "default": 5 }, "maxConcurrency": { "title": "Max Concurrency", "type": "integer", "description": "Maximum number of pages that can be processed at the same time.", "default": 10 }, "minConcurrency": { "title": "Min Concurrency", "type": "integer", "description": "Minimum number of pages that will be processed at the same time.", "default": 1 }, "maxRequestRetries": { "title": "Max Request Retries", "type": "integer", "description": "Number of times the crawler will retry a failed request before giving up. Keep this low (5-10) so a single deterministic error cannot burn the entire run timeout on retries.", "default": 10 }, "proxy": { "title": "Proxy configuration (optional override)", "type": "object", "description": "Leave empty to use a residential proxy automatically — on the pay-per-event build that is the actor's own built-in residential proxy at no extra cost to you; on the rental build it defaults to Apify Residential. Only set this if you want to use your own proxies. Do NOT select the Apify datacenter group: Facebook blocks datacenter IPs and returns an empty page for every request." } } }, "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 } } } } } } } } } }