Meta Ad Library Scraper

This Actor extracts complete public ad cards from Meta Ad Library with an ordinary unsigned Chromium browser. It does not sign in, dismiss login/cookie gates, persist sessions, inject fingerprints, modify browser-identification signals, call private APIs, or retry an access-control response.

Input

• query: 2–100 character keyword or advertiser.
• country: uppercase two-letter country code.
• maxItems: exact global cap from 1–100.
• adType: all or Meta's political/issue category. The old commercial value was removed because Meta has no distinct public commercial-only filter.
• platform: all, Facebook, Instagram, Audience Network, or Messenger.
• proxyConfiguration: standard Apify proxy input. Residential access is the default because local/datacenter requests may receive HTTP 403.

Input is strict. Unknown fields, numeric strings, lowercase country codes, invalid filter values, excessive limits, contradictory proxy settings, and secret-like custom proxy fields are rejected before browser launch.

Output

Every dataset row is a complete public ad identity with library ID/URL, advertiser name/page, ad text, status, normalized start date, query/filter context, source URL/status, extraction method, proxy state, and scrape time. Media and CTA fields are included only when they are directly rendered and can be normalized to public HTTPS URLs. Redirector CTA links are unwrapped to their public destination; unavailable optional values are omitted rather than written as null or empty strings.

Cards are bounded semantically by their unique Library ID, globally deduplicated by that ID, kept in rendered order, and lazy-loaded for at most ten bounded scroll rounds. Incomplete cards never count toward maxItems. A blocked, login-only, empty, or structurally unusable result writes no fake dataset rows, stores a diagnostics record in the default key-value store, and fails.

Safety and limitations

Only anonymously rendered public Ad Library content is collected. The Actor does not open ad-detail dialogs, play videos, accept cookies, authenticate, solve challenges, or access Meta's private GraphQL calls. Ad availability, status, creative URLs, result counts, and DOM structure can change. Use collected data in accordance with Meta's terms and applicable law.

Local QA

npm install --ignore-scripts
npm test
npm run check
npm audit --omit=dev
apify validate-schema
apify run --purge --input-file .actor/input.json

The local input intentionally disables proxy use so a network restriction is reported rather than hidden. test-input.json is the bounded three-item cloud fixture.