Facebook Ads Library Scraper — competitor ad research from the Facebook ad library

This Facebook Ads Library scraper turns the public Facebook Ad Library into structured data. Search any keyword or advertiser page and scrape Facebook ads with their copy, headlines, images and videos, call-to-action buttons, landing page links, run dates and the platforms they ran on — no Facebook account, cookies or API key needed. Teams use it for competitor ad research, creative swipe files, ad monitoring and political ad transparency work.

Give it a keyword such as nike, an advertiser page ID, or an Ad Library URL pasted from your browser, and get every matching ad back as JSON, CSV or Excel.

---

🚀 Key Features

• 🔎 Three ways to search — keywords, numeric advertiser page IDs, or Ad Library URLs copied straight from the browser, with the country and filters in the URL respected
• 🧾 Full ad creative — ad text, headline, link caption, CTA button and type, landing page URL, display format, and every image and video in the ad
• 🏷️ Advertiser details on every ad — page name, page ID, page URL, profile picture, page categories and page likes
• 🗳️ Political ad transparency — spend range, impressions range, currency and funding byline on ads that disclose them
• 🎛️ The Ad Library's own filters — creative type (video, image, meme, text-only), the platforms an ad ran on, and a date window, on top of status and category
• 🌍 Any Ad Library country — set a two-letter country code, or one per start URL
• 📑 Per-search limits — maxItems caps results per keyword, page ID or start URL, not per run
• 🛡️ No login — public data only; runs on Apify residential proxies by default
• 📤 Multiple export formats — JSON, CSV, Excel, XML via the Apify dataset
• 🔁 Schedulable runs — watch a competitor's page daily and diff what changed

---

✅ What You Get Here

• 💵 One charge per ad, and that is the whole bill. No Actor start fee, and no second charge to unlock ad details, advertiser data or enrichment — every field in the table below comes with the ad at the same price.
• 🗳️ Political spend and impressions in the same record. Ads in the political and issue category arrive with their spend range, impressions range, currency and funding byline already attached, not behind a separate detail step.
• 🖼️ The whole creative, not just the first frame. Every image and video in the ad, including carousel cards and the extra images and videos Facebook attaches beyond the main creative.
• 🏢 Advertiser context on every ad — page name, page ID, page URL, profile picture, page categories and page likes — so you do not need a second pass over advertiser pages to make the export usable.
• 🧬 Collation fields that tell repetition from variety. collationId and collationCount show when one creative was run many times, so 40 rows of the same ad do not read as 40 different ads.
• 🤖 Disclosure flags Facebook publishes but most exports drop — containsDigitalCreatedMedia for AI-generated or digitally altered media, and containsSensitiveContent.
• 🎯 Filters from a pasted URL are obeyed. Paste an Ad Library URL with its country, status, category, media type, platforms or date window already set and the run returns exactly the ads that URL shows in your browser, from the first result to the last.
• 🔍 Narrow the search before you pay for it. Ask for videos only, Instagram placements only, or ads that ran in a given window, and only the matching ads are returned and charged — you do not pay for a broad pull that you then filter yourself.
• 📐 maxItems counts per search, not per run, so one run can pull 100 ads for each of ten keywords without you splitting it into ten runs.

👥 Who Is This Actor For?

• Performance marketers — see which creatives and offers a competitor keeps running, and which they quietly stopped
• Creative strategists — build a swipe file of hooks, headlines and CTA patterns in a niche
• Agencies — audit a prospect's live ads before a pitch, and report on a client's share of voice
• Researchers and journalists — study political and issue ads with their disclosed spend and reach
• 🤖 AI builders — feed ad copy into a RAG pipeline or an agent that summarises a competitor's current messaging

💡 Common Use Cases

• Scrape Facebook ads for a brand and track how its creative rotates week to week
• Pull every active ad from one advertiser page ID before writing a competing campaign
• Collect ad copy and CTA buttons across a keyword to find the angles a market is using
• Monitor political and issue ads in one country with their spend and impressions ranges
• Export a creative library as CSV for a spreadsheet review with a client

---

📥 Input

Field	Type	Description	Default
searchTerms	Array	Keywords to search the Ad Library for. Each keyword is searched separately.	—
pageIds	Array	Numeric Facebook page IDs, to pull every ad from one advertiser.	—
startUrls	Array	Facebook Ad Library search URLs pasted from the browser. Country and filters in the URL override the settings below.	—
country	String	Two-letter country code of the Ad Library region to search.	US
adActiveStatus	String	all, active or inactive.	all
adType	String	all, political_and_issue_ads, housing_ads, employment_ads or credit_ads.	all
mediaType	String	Creative type to keep: all, image, meme, image_and_meme, video or none (text-only ads).	all
publisherPlatforms	Array	Keep only ads that ran on at least one of facebook, instagram, messenger, audience_network, whatsapp, threads. Empty means all platforms.	all
dateFrom	String	Keep ads that were running on or after this date (YYYY-MM-DD).	none
dateTo	String	Keep ads that were running on or before this date (YYYY-MM-DD).	none
maxItems	Integer	Maximum ads to scrape per keyword, page ID or start URL — not per run.	10
proxyConfiguration	Object	Proxy settings. Residential is the default and the setting this Actor is tested on.	Apify Proxy, RESIDENTIAL

At least one of searchTerms, pageIds or startUrls is required.

Example Input

{
  "searchTerms": ["nike"],
  "country": "US",
  "adActiveStatus": "all",
  "adType": "all",
  "mediaType": "video",
  "publisherPlatforms": ["instagram"],
  "dateFrom": "2026-01-01",
  "dateTo": "2026-09-30",
  "maxItems": 50,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}

---

🔗 Supported URL Types

URL Type	Example
Keyword search	https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&q=nike&search_type=keyword_unordered
Advertiser page	https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=GB&view_all_page_id=15087023444&search_type=page

---

📤 Output

Each dataset item is one ad. Fields that the Ad Library does not disclose come back as null.

Field	Type	Description
adArchiveId	String	The ad's Ad Library ID
collationId	String	Groups near-identical ads that ran together
collationCount	Number	How many ads are in that group
pageId	String	Advertiser's Facebook page ID
pageName	String	Advertiser's page name
pageUrl	String	Advertiser's Facebook page URL
pageProfilePictureUrl	String	Advertiser's profile picture
pageCategories	Array	Categories on the advertiser's page, e.g. ["Nonprofit organization"]
advertiserName	String	Name the ad is attributed to
byline	String	Funding entity on political and issue ads
isActive	Boolean	Whether the ad was still running
startDate	String	ISO date the ad started
endDate	String	ISO date the ad stopped, when it has
totalActiveTime	Number	Seconds the ad has run, when disclosed
publisherPlatforms	Array	Where it ran: FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK
adText	String	The ad's body copy
adTitle	String	The ad's headline
linkUrl	String	Landing page the ad points to
linkCaption	String	Display domain under the headline
ctaText	String	Call-to-action button label, e.g. Shop Now
ctaType	String	Call-to-action type, e.g. SHOP_NOW
displayFormat	String	Creative format: IMAGE, VIDEO, CAROUSEL, DCO
categories	Array	Ad Library category, e.g. ["POLITICAL"]
images	Array	Image URLs in the ad
videos	Array	{ url, preview } for each video
pageLikes	Number	Likes on the advertiser's page
impressionsText	String	Impressions range — political and issue ads only
spendText	String	Spend range — political and issue ads only
currency	String	Currency of the spend range
reachEstimate	Number	Estimated reach, when disclosed
containsSensitiveContent	Boolean	Ad Library sensitive-content flag
containsDigitalCreatedMedia	Boolean	Whether the ad declares AI-generated or digitally created media
countryIsoCode	String	Country the creative snapshot came from
adLibraryUrl	String	Direct link to the ad in the Ad Library
searchTerm	String	The keyword this ad was found with
searchPageId	String	The advertiser page ID this ad was found with
country	String	The Ad Library country searched

Example Output

{
  "adArchiveId": "832851291236798",
  "collationId": "1033278991403571",
  "pageId": "54779960819",
  "pageName": "United Nations",
  "pageUrl": "https://www.facebook.com/unitednations/",
  "pageProfilePictureUrl": "https://scontent.fjed5-2.fna.fbcdn.net/v/t39.35426-6/314780285_700685748005646_8648629021855123542_n.jpg",
  "pageCategories": ["Organization"],
  "advertiserName": "United Nations",
  "byline": "United Nations with Facebook Ad Credits",
  "collationCount": 1,
  "isActive": false,
  "startDate": "2022-11-07T08:00:00.000Z",
  "endDate": "2023-01-08T08:00:00.000Z",
  "totalActiveTime": null,
  "publisherPlatforms": ["FACEBOOK", "INSTAGRAM"],
  "adText": "Leaders gathered at the UNGA to tackle global challenges. You can also help protect our planet by taking climate action.",
  "adTitle": "United Nations",
  "linkUrl": "https://api.whatsapp.com/send",
  "linkCaption": "api.whatsapp.com",
  "ctaText": "Send WhatsApp message",
  "ctaType": "WHATSAPP_MESSAGE",
  "displayFormat": "CAROUSEL",
  "categories": ["POLITICAL"],
  "images": [
    "https://scontent.fjed5-2.fna.fbcdn.net/v/t39.35426-6/314001595_822824655694557_5447234307407707513_n.jpg"
  ],
  "videos": [],
  "pageLikes": 8967118,
  "impressionsText": ">1M",
  "spendText": "€15K - €20K",
  "currency": "EUR",
  "reachEstimate": null,
  "containsSensitiveContent": false,
  "containsDigitalCreatedMedia": false,
  "countryIsoCode": "DE",
  "adLibraryUrl": "https://www.facebook.com/ads/library/?id=832851291236798",
  "searchTerm": "climate",
  "searchPageId": null,
  "country": "US"
}

You can export the dataset as JSON, CSV, Excel, XML, RSS, or HTML from the Apify Console or via the Apify API.

---

💰 Pricing

This Actor is pay per event — you pay per ad returned: $0.0005 per ad, so 1,000 ads cost $0.50, plus Apify platform usage.

That is the only event it charges. There is no Actor start fee, so a run that returns 12 ads costs 12 ads' worth, and there is no extra charge for ad details, advertiser data or enrichment. A run that finds no matching ads returns nothing and charges nothing. A free Apify account is enough to try it.

---

❓ FAQ

What is the Facebook Ads Library Scraper?

It is a Facebook Ads Library scraper that reads the public Facebook ad library and returns each ad as a structured record — copy, creative, CTA, landing page, dates, platforms and advertiser. You search by keyword, advertiser page ID or Ad Library URL.

Do I need an account, cookies or an API key?

No. It reads only what the Ad Library shows the public, so there is no login, no cookies and no Facebook API token.

Do I need a proxy?

Keep the residential default — it is the setting this Actor is tested on, and the one these figures were measured with. You do not need to configure anything else.

Is there a start fee or a minimum charge?

No. The only event this Actor charges is one per ad returned, at $0.0005. There is no per-run start fee and no separate charge for ad details, advertiser information or enrichment, so a small test run costs only the ads it returns.

How many ads can I get per run?

maxItems applies per keyword, page ID or start URL, so three keywords with maxItems: 100 return up to 300 ads. The Ad Library reports how many ads match your search in the run log, and paging continues until maxItems or the end of the results.

Does it handle pagination automatically?

Yes. Each search runs to maxItems or to the last matching ad, whichever comes first — you do not need to page, resume or stitch runs together.

Which ads show spend and impressions?

Only ads in the political and issue category disclose spend ranges, impressions ranges and a funding byline — that is a Facebook policy, not a limit of this Actor. Commercial ads return null for those fields. Set adType to political_and_issue_ads to search only the ads that disclose them.

Can I filter by creative type or platform?

Yes. mediaType keeps only videos, images, memes, images-and-memes, or text-only ads (none), and publisherPlatforms keeps only ads that ran on the placements you pick — Facebook, Instagram, Messenger, Audience Network, WhatsApp or Threads. Both are the Ad Library's own filters, so only matching ads are returned and charged. Facebook decides which platforms it lists for an ad, so a small number of results can come back without the exact placement you asked for.

How does the date filter work?

dateFrom and dateTo match ads that were running in that window, which is how the Ad Library's own date filter behaves — not ads that started inside it. An ad that started before dateFrom and was still running afterwards is included, so a window of 2020-01-01 to 2020-12-31 returns ads whose run overlaps 2020. Either field works on its own.

Can I search a specific advertiser?

Yes. Put the numeric page ID in pageIds, or paste the advertiser's Ad Library URL (the one with view_all_page_id=) into startUrls.

Can I schedule it or integrate it with my app?

Yes — every Apify Actor exposes a REST API, webhooks, and integrations with Zapier, Make, Google Sheets and Slack, and can be called from an AI agent via the Apify MCP server.

Is it legal to scrape Facebook ads?

This Actor accesses only the publicly available Ad Library, which Facebook publishes for ad transparency. You are responsible for making sure your use complies with Facebook's terms of service and the laws in your jurisdiction.

What if Facebook changes and the Actor breaks?

Open an issue on the Actor's Issues tab — that is the most direct route to a fix. The Ad Library changes regularly and the Actor is maintained against it, so most changes are absorbed without you doing anything.

---

🧩 Part of the Facebook Scraper Suite

Goldmine's Facebook Scraper Suite covers the public surfaces of Facebook — ads, groups and pages. Also try:

• Facebook Group Scraper — posts, authors, reactions and photos from public Facebook groups
• Facebook Posts Scraper — posts from public Facebook pages and profiles, with reactions, comments and shares
• Facebook Page Details Scraper — followers, category, contact details and about text for a page, one row per page
• Facebook Comments Scraper — comments and replies on public posts, videos, reels and photos

See every Goldmine Actor at apify.com/logical_scrapers.

---

📷 Image Credit

Image credit: facebook.com

---

📬 Contact & Support

• Issues & feature requests: use the Issues tab on this Actor's page — that is the most direct route to a fix.
• Email: coredev.dan@gmail.com
• If this Actor saved you time, please leave a ⭐ rating on the Apify Store. It helps us keep it maintained.