Meta Ads Library Scraper

A production-ready Apify Actor that extracts ad data from the Meta (Facebook) Ads Library with advanced bot-detection bypass, deep data extraction via GraphQL, and human-behaviour simulation.

---

Features

• Bypasses bot detection — advanced fingerprint evasion, TLS randomisation, and geo-aligned browser profiles keep the scraper undetected
• Deep data extraction — captures Facebook's internal API responses for richer, more complete ad data than DOM scraping alone
• Behaves like a real user — randomised scrolling, mouse movement, and timing patterns avoid triggering rate limits
• Optional proxy — Apify residential or datacenter proxy when you need geo-specific egress or to recover from HTTP 403
• Infinite-scroll handling — automatically loads more ads as you scroll
• Flexible output — basic, detailed, or full ad data formats

---

Input

Provide either startUrls (direct Ads Library URLs) or a searchQuery (and optional filters). Defaults below match INPUT_SCHEMA.json.

Parameter	Type	Default	Description
startUrls	array	—	Optional. List of https://www.facebook.com/ads/library/... URLs; when set, searchQuery and filter fields are ignored
searchQuery	string	Nike	Search term (e.g. company name, keyword). Ignored when startUrls is provided
country	string	ALL	Country code for ad targeting (e.g. US, IT, GB)
adType	string	ALL	Ad type filter: ALL, POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, EMPLOYMENT_ADS, CREDIT_ADS
maxAds	integer	5	Maximum number of ads to scrape (1–10 000)
includeInactive	boolean	false	Include inactive (ended) ads
proxyConfiguration	object	Apify proxy off (useApifyProxy: false)	Optional. Turn on Apify Proxy and e.g. apifyProxyGroups: ["RESIDENTIAL"] if you see HTTP 403 or need geo-specific egress
outputFormat	string	detailed	Output format: basic, detailed, or full
delayBetweenRequests	integer	3000	Delay between scroll iterations in ms (1 000–10 000)
pageId	string	—	Optional Facebook Page ID to scope the search
enableGraphQLInterception	boolean	true	Intercept Meta's GraphQL API for richer ad data. Must be true to populate platforms — disabling this leaves platforms as null on every record
fetchAdDetails	boolean	true	Open the details panel per ad (richer fields; slower, ~1–3 s extra per ad)
debugScreenshots	boolean	false	Save debug screenshots to the key-value store when no ads are found

---

Output

Each item in the default dataset represents one ad and includes:

• adId — Facebook Library ID
• pageName — advertiser page name
• adContent — ad body text
• startDate / endDate — ad flight dates
• impressions / spend / reach — performance ranges
• platforms — Facebook, Instagram, Messenger, Audience Network, Threads (requires enableGraphQLInterception: true)
• adCreative — image/video URLs
• landingPageUrl / ctaText — call-to-action
• isActive — whether the ad is currently running
• source — graphql_interception or dom_extraction

---

Pricing Model — Pay Per Event

This Actor uses the Pay Per Event pricing model. You are charged for the specific operations performed during a run, not a flat rental fee. Prices are set in Apify Console and are not listed here. Event names and triggers are documented in docs/PPE_BILLING_EVENTS.md.

What is charged automatically

Apify charges these events without any action required from you:

Event	When
Actor start	Once per run
Dataset item	Once per ad record saved

What is charged in code

Event	When	Frequency
Residential proxy (run fee)	proxyConfiguration uses a proxy group (e.g. RESIDENTIAL)	Once per run
Datacenter proxy (run fee)	Apify Proxy without groups, or custom proxyUrls	Once per run
Proxy record surcharge	Any proxy is enabled for the run	Once per ad record saved
GraphQL record surcharge	enableGraphQLInterception is true	Once per ad record saved
Ad details fetch	fetchAdDetails is true and details are returned for an ad	Per successful details fetch
Debug screenshot	debugScreenshots is true and a screenshot is saved	Per screenshot saved
Memory surcharge	Run is allocated more than 2 GB RAM	1 event per GB above 2 GB baseline, once per run

Memory surcharge examples

Memory	Memory surcharge events
2 GB	0
3 GB	1
4 GB	2
8 GB	6
16 GB	14

Runs of this Actor on Apify use at least 2 GB RAM (actor.json).

Spending limits

You can set a maximum cost per run in Apify Console. The Actor respects this limit:

• If the limit is reached during startup charges, the run exits gracefully before scraping begins.
• If the limit is reached mid-scrape, the current batch is completed and the run exits — all data already collected is preserved.

Proxy

Default: Apify Proxy is off in the input schema — many runs work without it.

If Meta returns HTTP 403 or you need traffic from a specific region, enable Apify Proxy and use a RESIDENTIAL group (apifyProxyGroups: ["RESIDENTIAL"]) in proxyConfiguration.

---

Memory Requirements

This Actor runs a full browser session. actor.json sets minMemoryMbytes to 2048, so Apify runs use at least 2 GB (2048 MB) of RAM; you cannot allocate below that for this Actor. Increase memory in Apify Console for very large maxAds or if you see out-of-memory warnings.

• Minimum and default: 2 GB (2048 MB) — minMemoryMbytes / defaultRunOptions.memoryMbytes in actor.json
• Maximum (Actor cap): 32 GB