# Facebook Marketplace Scraper Pro (`ayeeyee/facebook-marketplace-scraper-pro`) Actor Scrape Facebook Marketplace listings with seller info, prices, locations, and media. Multi-provider fallback chain (desktop Playwright + mobile HTML). Category + location filters. MCP-ready providerHealth. No paid API keys. - **URL**: https://apify.com/ayeeyee/facebook-marketplace-scraper-pro.md - **Developed by:** [Virtual Footprint LLC](https://apify.com/ayeeyee) (community) - **Categories:** Social media - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 listing extracteds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Facebook Marketplace Scraper Pro ![Apify](https://img.shields.io/badge/Apify-Actor-ff6b37?logo=apify) ![Version](https://img.shields.io/badge/version-1.0-blue) ![Pricing](https://img.shields.io/badge/pricing-PAY_PER_EVENT-success) ![Modes](https://img.shields.io/badge/modes-fast_lookup%7Cenrich%7Cbatch-orange) ![MCP-ready](https://img.shields.io/badge/MCP-ready-brightgreen) > Facebook Marketplace listings with reliable seller info, price/condition/location filters, and MCP-ready providerHealth. Multi-provider fallback. No paid API keys. --- ### Why This Actor Is Better The Facebook Marketplace scraper that actually works. Built to fix the #1 complaint about the incumbent (Apify's own official actor has seller=null bugs): this actor reliably extracts seller name, profile URL, rating, and member-since from every listing. Multi-provider fallback (Playwright desktop + mobile HTML), price/condition/ location filters, media extraction, and MCP-ready providerHealth metadata. #### Key Features - Reliable seller extraction — name, profile URL, rating (fixes the incumbent's null-seller bug) - Multi-provider fallback — Playwright desktop primary, mobile HTML fallback when blocked - Price + condition + location filters — slice by budget, condition tier, and radius - Media extraction — primary and secondary listing images - Price bands — automatic budget/value/mid/premium/luxury classification - Contact extraction — emails and phones from listing descriptions - Confidence scoring — every listing gets a 0.0-1.0 score weighted by seller presence and completeness - Source attribution + providerHealth — MCP agents can route around failed providers - Cache-first mode — fast_lookup hits the Apify KVS cache for sub-second repeat queries - Transparent PPE pricing — $2/1K listings, $0.50/1K with seller info --- ### Architecture ```` Input (queries + mode) | v \[Cache check] --hit--> return base data (<800ms) |miss v \[Primary provider: scrape\_marketplace\_desktop] |-- on failure --> \[Fallback provider] v \[Normalization + field mapping] | v \[Enrichment layer] | v \[Confidence scoring + source attribution + providerHealth] | v \[Progressive dataset push] (one push per result) | v \[Webhook + MCP-ready metadata] ```` Every result includes `providerHealth{}` tracking per-provider status, latency, and errors — making this actor safe to call from MCP agents that need to route around failures. --- ### Modes | Mode | Description | Target latency | Use case | |---|---|---|---| | `fast_lookup` | Cache-first, base data only | <800ms cached | Quick lookups, deduplication | | `enrich` | Full enrichment with contact extraction + scoring | ~2-4s/result | Detailed analysis | | `batch` | Queue-based, full enrichment, per-item isolation | varies | Large query lists (100+) | --- ### Input | Parameter | Type | Required | Default | Description | |---|---|:---:|---|---| | `mode` | string | — | `enrich` | `fast_lookup` \| `enrich` \| `batch` | | `queries` | array | yes | `["iphone 15 pro"]` | Search queries | | `maxResults` | integer | — | `25` | Max results per query (1-1000) | | `webhookUrl` | string | — | — | Webhook for completion notification | #### Example input ```json { "mode": "enrich", "queries": ["iphone 15 pro"], "maxResults": 50 } ```` *** ### Output Results are stored in the Apify dataset as structured JSON. See `.actor/output_schema.json` for the canonical schema. Every result includes: | Field | Type | Description | |---|---|---| | `confidenceScore` | number | 0.0-1.0 reliability score | | `sources` | array | Provider attribution | | `providerHealth` | object | Per-provider status/latency/error for MCP routing | | `cacheStatus` | string | `hit` | `miss` | `degraded` | | `mode` | string | Execution mode used | | `extractedAt` | string | ISO timestamp | *** ### Pricing Transparent pay-per-event (PPE) pricing. You only pay for successful results. | Event | Price | When charged | |---|---|---| | Actor Start | $0.05/1K runs | One-time per run | | Result | $0.002/result | Per result pushed | | Seller Extracted | $0.0005/result | Charge per listing with full seller info (name, profile, rating). | No monthly subscription required. *** ### Use Cases - Reseller / flipper sourcing — find undervalued items across markets - Drop-shipping research — monitor competitor pricing by category - Market research — track listing volume and price trends by location - Lead generation — extract seller contact info from business listings - Real estate (apartments) — scrape rental listings with landlord contacts - Inventory monitoring — alert when new items match your criteria - MCP agent workflows — call from LLM agents; providerHealth lets agents route around blocks *** ### Integration Examples #### Python (Apify SDK) ```python from apify_client import ApifyClient client = ApifyClient("YOUR_APIFY_TOKEN") run = client.actor("YOUR_USERNAME/facebook-marketplace-scraper-pro").call(run_input={ "mode": "enrich", "queries": ["iphone 15 pro"], "maxResults": 50, }) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) ``` #### cURL ```bash curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~facebook-marketplace-scraper-pro/runs?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"mode":"enrich","queries":["iphone 15 pro"],"maxResults":25}' ``` #### MCP (Model Context Protocol) This actor is MCP-ready. Register it via `@apify/actors-mcp-server`: ```bash npx -y @apify/actors-mcp-server --tools actors,YOUR_USERNAME/facebook-marketplace-scraper-pro ``` Agents can then call `call-actor` and use `providerHealth` + `confidenceScore` to route around failed providers and filter result quality. *** ### FAQ **Q: Do I need Facebook login cookies?** No. This actor scrapes public Marketplace listings via Playwright + httpx. No login or session cookies required for public listings. **Q: Why does the incumbent's seller field return null?** The incumbent uses a single selector path that breaks when Facebook changes its DOM. This actor uses multiple selector fallbacks (profile link, marketplace profile, seller badge) plus a dedicated per-listing fetch, so seller info is reliably extracted. **Q: How does the fallback chain work?** The primary Playwright desktop scrape handles JS-rendered search results. If Facebook blocks Playwright (login wall, CAPTCHA, timeout), the actor falls back to mobile HTML via httpx. The providerHealth field shows which providers succeeded. **Q: Can I filter by price and condition?** Yes. Use minPrice/maxPrice for price range, condition for new/used tiers, and location+radius for geographic scoping. **Q: Can I call this from an LLM agent?** Yes. The actor is MCP-ready. Every result includes providerHealth{}, confidenceScore, and priceBand so agents can make routing and filtering decisions. *** ### Legal & Compliance This actor scrapes **publicly available** data. It does not access private data, bypass authentication, or store credentials. Users are responsible for complying with applicable data protection laws (GDPR, CCPA, etc.) and the target platform's Terms of Service. This actor is intended for legitimate research, analysis, and outreach use cases. It must not be used for spam, harassment, or unlawful activity. *** ### AI-DLC / Data Lifecycle This actor follows AI-DLC principles for ethical data handling: - **Collection** — Public data only; respects robots.txt and rate limits. - **Processing** — In-memory normalization; no PII logging. - **Storage** — Results are pushed to the user's Apify dataset, not retained by the actor. - **Usage** — Designed for analysis, enrichment, and legitimate outreach. - **Disposal** — No long-term caching of user data between runs (cache TTL 1800s for base results only). *** ### Enhancement Roadmap (API / MCP Integrations) - Multi-step orchestration via LangGraph conditional workflows - Vector store integration for semantic deduplication across runs - Additional paid enrichment APIs (user keys, disabled by default) *** ### Changelog - v1.0 — Initial release: reliable seller extraction, price/condition/location filters, Playwright+mobile fallback, MCP-ready metadata *** ### Links - **Apify Store:** https://apify.com/YOUR\_USERNAME/facebook-marketplace-scraper-pro - **Documentation:** See this README - **Support:** Open an issue on the actor's Apify Store page # Actor input Schema ## `mode` (type: `string`): fast\_lookup: cache-first. enrich: full with seller+media. batch: queue-based. ## `queries` (type: `array`): Search keywords, category URLs, or listing URLs ## `maxResults` (type: `integer`): Maximum results per query (1-1000) ## `webhookUrl` (type: `string`): Optional webhook URL for completion notification ## `location` (type: `string`): City or postal code to scope listings (e.g. 'New York' or '10001'). ## `radius` (type: `integer`): Search radius in kilometers from the location. 0 = exact location. ## `minPrice` (type: `number`): Filter listings at or above this price. 0 = no min. ## `maxPrice` (type: `number`): Filter listings at or below this price. 0 = no max. ## `condition` (type: `string`): Filter by condition: new, used\_like\_new, used\_good, used\_fair, or empty for all. ## `maxListings` (type: `integer`): Hard cap on listings returned per query (default 100). ## `includeSellerInfo` (type: `boolean`): Extract seller name, profile URL, rating, and member-since. (The incumbent's #1 complaint is this being null.) ## Actor input object example ```json { "mode": "enrich", "queries": [ "iphone 15 pro" ], "maxResults": 25, "webhookUrl": "", "location": "", "radius": 50, "minPrice": 0, "maxPrice": 0, "condition": "", "maxListings": 100, "includeSellerInfo": true } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("ayeeyee/facebook-marketplace-scraper-pro").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("ayeeyee/facebook-marketplace-scraper-pro").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call ayeeyee/facebook-marketplace-scraper-pro --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=ayeeyee/facebook-marketplace-scraper-pro", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook Marketplace Scraper Pro", "description": "Scrape Facebook Marketplace listings with seller info, prices, locations, and media. Multi-provider fallback chain (desktop Playwright + mobile HTML). Category + location filters. MCP-ready providerHealth. No paid API keys.", "version": "1.0", "x-build-id": "pf9r5pvET7UYh9LYC" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ayeeyee~facebook-marketplace-scraper-pro/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ayeeyee-facebook-marketplace-scraper-pro", "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/ayeeyee~facebook-marketplace-scraper-pro/runs": { "post": { "operationId": "runs-sync-ayeeyee-facebook-marketplace-scraper-pro", "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/ayeeyee~facebook-marketplace-scraper-pro/run-sync": { "post": { "operationId": "run-sync-ayeeyee-facebook-marketplace-scraper-pro", "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", "required": [ "queries" ], "properties": { "mode": { "title": "Execution Mode", "enum": [ "fast_lookup", "enrich", "batch" ], "type": "string", "description": "fast_lookup: cache-first. enrich: full with seller+media. batch: queue-based.", "default": "enrich" }, "queries": { "title": "Search Queries", "type": "array", "description": "Search keywords, category URLs, or listing URLs", "default": [ "iphone 15 pro" ] }, "maxResults": { "title": "Max Results per Query", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum results per query (1-1000)", "default": 25 }, "webhookUrl": { "title": "Webhook URL", "type": "string", "description": "Optional webhook URL for completion notification", "default": "" }, "location": { "title": "Location", "type": "string", "description": "City or postal code to scope listings (e.g. 'New York' or '10001').", "default": "" }, "radius": { "title": "Search radius (km)", "type": "integer", "description": "Search radius in kilometers from the location. 0 = exact location.", "default": 50 }, "minPrice": { "title": "Minimum price", "type": "number", "description": "Filter listings at or above this price. 0 = no min.", "default": 0 }, "maxPrice": { "title": "Maximum price", "type": "number", "description": "Filter listings at or below this price. 0 = no max.", "default": 0 }, "condition": { "title": "Condition", "type": "string", "description": "Filter by condition: new, used_like_new, used_good, used_fair, or empty for all.", "default": "" }, "maxListings": { "title": "Max listings per query", "type": "integer", "description": "Hard cap on listings returned per query (default 100).", "default": 100 }, "includeSellerInfo": { "title": "Extract seller info", "type": "boolean", "description": "Extract seller name, profile URL, rating, and member-since. (The incumbent's #1 complaint is this being null.)", "default": true } } }, "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 } } } } } } } } } } ```