Kuantum Facebook Marketplace Scraper — Public Listings

This Actor extracts evidenced fields from publicly accessible Facebook Marketplace search and listing pages. It does not use login cookies, bypass access controls, or claim coverage when Facebook presents a login or bot-check wall.

Provide keywords, areas, and/or zipCodes to generate best-effort Marketplace searches, or provide explicit searchUrls and/or listingUrls. Each keyword is paired with each area and ZIP code. Search pages are used only to discover public /marketplace/item/ links; direct listing pages are then inspected for title, price, currency, location, seller, description, and images when those fields are published in the page.

Every run writes the same headered results to the default dataset and to the Key-Value Store:

• OUTPUT_MD — Markdown table
• OUTPUT_CSV — CSV with column headers
• OUTPUT_XLSX — Excel workbook (Listings sheet) with column headers

The output columns are listing_url, listing_id, source, search_keyword, search_area, search_zip_code, title, price, currency, location, seller_name, description, image_urls, date_published, contact_info, observed_at, first_seen_at, previous_price, price_change, collection_status, and error. date_published and contact_info are populated only when Facebook exposes them publicly; the Actor does not guess or bypass access controls to obtain them.

When monetized, Apify charges one listing-collected event per usable listing row. Login, blocked, filtered, and failed rows are not charged. The run summary reports chargedListings.

Use maxScrolls to control how many additional times each search page is scrolled to discover more links. Set infiniteScroll to continue until maxItems is reached or two scrolls add no new links; it has a 100-scroll safety ceiling. maxRetries, requestDelayMs, listingTimeoutMs, and maxConcurrency control reliability and throughput. The circuit breaker is enabled by default: stopOnAccessBlock stops the run after one Facebook login, security, bot-check, 403, or 429 signal; use maxBlockedPages only when a higher threshold is deliberately needed. Each search page is saved as SEARCH_###_HTML, SEARCH_###_SCREENSHOT, and SEARCH_###_SUMMARY for diagnostics. minPrice and maxPrice optionally mark out-of-range listings as filtered_out. A named marketplace-state store tracks first-seen and prior prices across runs, allowing previous_price and price_change fields. maxHistoryItems bounds retained history. Set alertWebhookUrl to receive run-complete and price-drop JSON notifications; set alertOnNewListing to also receive new-listing events. fallbackApiUrl (and optionally fallbackApiToken) uses an authorized provider when Facebook discovery returns fewer than maxItems; it must return a JSON array or {items: []}. Login, bot-check, metadata, and navigation failures are included as rows with collection_status and error, and are also summarized in FAILURES.

An empty result caused by a login/access wall is a successful run with outcome: "no_results_or_access_blocked"; inspect the diagnostic HTML, screenshot, and FAILURES entries.

Authorized Facebook session

The Actor can load session state from the protected facebook-session Key-Value Store when useFacebookSession is enabled. Capture it from an existing signed-in Chrome session with node scripts/capture-facebook-session.mjs; use the printed store ID as facebookSessionStoreId in Actor input. The script never asks for or stores your Facebook password. Session state expires and must be renewed when Facebook requests verification.

For a local authorized search and export, close the dedicated Chrome profile and run:

$node scripts/search-marketplace.mjs --keyword "Michael Jordan card" --area Orlando --max-items 25 --infinite

When cloud search returns no listing links, use node scripts/capture-marketplace-search.mjs with SEARCH_URL to collect authorized search results from the signed-in browser. It stores listing URLs only under CAPTURED_LISTING_URLS; pass that store ID as capturedListingStoreId to the Actor. The Actor then enriches those URLs in the cloud.

Scheduling

Apify schedules are account-level resources. Create one deliberately with:

$APIFY_TOKEN="$APIFY_TOKEN" ACTOR_ID=bczOsNg3SNbHUqjHm CRON_EXPRESSION="0 * * * *" TIMEZONE="America/New_York" node scripts/create-schedule.mjs

Use SCHEDULE_INPUT_JSON to provide the normal Actor input. The script defaults to hourly execution; review the schedule and expected Apify costs before enabling it.

Use only URLs and data you are authorized to observe and process, and follow Facebook’s terms and applicable law.