Facebook Ads Library Scraper

Scrape Facebook Ad Library ads by keyword, advertiser Page ID, direct Ad ID, or "Paid for by" funding-entity name. Get ad creative text, media, landing page links, run dates, platform breakdown, creative-reuse counts, page follower counts, and — for political, issue, and EU-eligible ads — real spend, impressions, and disclaimer data. Residential proxy included automatically; no cookies or Facebook login required by default.

What this actor does

• Four search modes — keyword, advertiser Page ID, direct Ad ID, or "Paid for by" funding-entity name, all in a single run
• Filters — country, content language, ad status (active/inactive), ad category (political & issue, housing, employment, credit), media type, date range, sort order
• Creative-reuse signal — collation_count shows how many ad variations share the same creative and text, a common "this is scaling" signal
• Real political & issue-ad data — spend range, impressions, reach, and "Paid for by" disclaimer info for political, issue, and EU-eligible ads, never estimated for ordinary commercial ads
• Empty fields are omitted — you'll never see null in the output

Output per ad

• ad_id — unique Facebook ad archive ID
• page_name — advertiser's Facebook Page name
• ad_text — ad creative copy
• ad_snapshot_url — link to view the ad on Facebook Ad Library
• start_date / end_date — when the ad started/stopped running
• status — active / inactive / unknown
• platforms — Facebook, Instagram, Messenger, Audience Network, Threads
• media_type / media_url — image, video, meme, or none, with the media URL
• cta_text — call-to-action button text
• link_url — the ad's destination URL
• collation_count — number of ad variations sharing this creative/text
• page_like_count / page_categories — advertiser page's follower count and category tags
• gated_type — whether the ad is eligible for Meta's political/EU transparency data
• disclaimer_label / byline — "Paid for by" disclaimer type and funding-entity name (political/issue ads)
• spend / impressions / reach_estimate / currency — political, issue, and EU-eligible ads only
• regional_regulation_data — region-specific regulatory flags (e.g. financial-services, anti-scam limited-delivery status)
• contains_digital_created_media — whether Meta's AI-generated-content disclosure applies
• search_term — the keyword / Page ID / Ad ID / byline that found this ad
• scraped_at — when the record was scraped

Input

Field	Type	Default	Description
searchTerms	array	–	Keywords or page names to search
pageIds	array	–	Facebook Page IDs — fetch all ads run by a specific advertiser
adIds	array	–	Direct Ad Library IDs to fetch specific ads
bylines	array	–	"Paid for by" funding-entity/committee name to search
country	string	ALL	Single country code (e.g. US, GB) or ALL
countries	array	–	Country code(s) to search (only the first entry is applied)
contentLanguages	array	–	2-letter ISO language codes to filter ad content language
adActiveStatus	string	active	all / active / inactive
adType	string	all	all / political_and_issue_ads / housing / employment / credit
mediaType	string	all	all / image / video / meme / none
startDate / endDate	string	–	Date range filter (YYYY-MM-DD)
sortBy	string	relevance	relevance / total_impressions
resultsPerSearch	integer	50	Max ads per search term / page / ad / byline (1–500)
cookies	string	–	Optional Facebook cookies for more reliable, login-gated access

At least one of searchTerms, pageIds, adIds, or bylines is required.

Example: keyword search

{
    "searchTerms": ["nike", "adidas"],
    "country": "US",
    "adActiveStatus": "active",
    "resultsPerSearch": 20
}

Example: all ads run by an advertiser

{
    "pageIds": ["15087023444"],
    "country": "US",
    "resultsPerSearch": 100
}

Example: political ad spend by funding entity

{
    "bylines": ["DNC"],
    "adType": "political_and_issue_ads",
    "country": "US",
    "resultsPerSearch": 50
}

Example: video ads only, sorted by reach

{
    "searchTerms": ["shoes"],
    "mediaType": "video",
    "sortBy": "total_impressions",
    "resultsPerSearch": 30
}

Use cases

• Competitive intelligence — monitor competitors' live ad creative, copy, and landing pages
• Ad creative research — find high-performing, widely-reused ad variations via collation_count
• Political & campaign finance research — track spend, impressions, and the funding entities behind political and issue ads
• Marketing agencies — build swipe files and client pitch decks from real, currently running ads
• Compliance & brand monitoring — audit how a brand, competitor, or affiliate is advertising
• Academic & journalism research — bulk-export ad transparency data for a topic, advertiser, or funding entity

FAQ

Is this affiliated with Meta or Facebook? No — this is an independent third-party actor that reads the public Facebook Ad Library, the same data available at facebook.com/ads/library.

Do I need Facebook cookies or to log in? No, not by default. Facebook occasionally gates Ad Library search behind a login page on certain IPs; supplying optional cookies from a logged-in browser session makes search more reliable when that happens.

Why is a residential proxy always used? Facebook blocks Ad Library data from data center IPs, so residential proxy is built in automatically — there's nothing to configure.

Why do some ads have no spend/impressions data? Facebook only discloses spend, impressions, and reach for political, issue, and EU-regulated ads. This actor never estimates or fabricates that data for ordinary commercial ads — it's honestly left out of the output instead.

Can I search multiple countries at once? Not yet — Facebook's Ad Library doesn't support multi-country search server-side, so only the first entry in countries is applied.

What's the "Paid for by" / byline search for? It finds ads whose funding-entity disclaimer (shown as "Paid for by X" on political/issue ads) matches your input — useful for tracking who's funding a given ad campaign.

What does collation_count mean? The number of ad variations Facebook groups under the same underlying creative and text — a quick signal for how heavily an ad is being scaled.

How far back does the data go? Facebook's Ad Library retains active ads plus roughly 7 years of political and social-issue ad history; this actor surfaces whatever Facebook currently serves for a given search.