Facebook Marketplace Scraper Pro

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

{
  "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)

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

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:

$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