Facebook Ads Library Scraper | Meta Ad Library API
Pricing
from $1.50 / 1,000 results
Facebook Ads Library Scraper | Meta Ad Library API
See competitors' Facebook and Instagram ads from the Meta Ad Library by keyword, page or link, any country: ad text, landing page, CTA, images, videos, start date, days running and political spend.
Pricing
from $1.50 / 1,000 results
Rating
0.0
(0)
Developer
Philip Kirkbride
Maintained by CommunityActor stats
0
Bookmarked
6
Total users
1
Monthly active users
17 hours ago
Last modified
Categories
Features
Share
Facebook Ads Library Scraper (Meta Ad Library)
See every ad your competitors run on Facebook, Instagram, Messenger, Threads and WhatsApp. Search the Meta Ad Library by keyword, by advertiser page or with a link you already filtered on the site, and get each ad as a clean spreadsheet row: ad text, headline, landing page, call to action, images and video links, start and end dates, days running, platforms, the advertiser's page and likes, and, for political and issue ads, spend and impression ranges with the paid-for-by name.
Press Start with the example search to see real ads in seconds. No Facebook account, no setup.
- Search like the Ads Library site: keywords (any words or exact phrase), advertiser pages, any country or all countries, active or past ads, media type and ad category (political and issue, housing, employment, financial).
- Filter by date: only ads shown in a date range, or in the last 7 or 30 days.
- Sort newest first to see the ads advertisers launched most recently, or by most impressions.
- EU transparency details: for ads shown in the EU, see how many people each ad reached, broken down by country, age and gender, the audience it targeted, and who paid for it and who benefits.
- New-ads feed: schedule a run and get only the ads that appeared since the last one. Ads you already have are skipped and not charged.
- Hundreds or thousands of ads per search, paged automatically, with duplicates removed across searches.
Use cases
- Competitor ad research: list every ad a competitor is running right now, with the text, offer, landing page and call to action they test, and how long each has been running.
- Creative inspiration (ad spy): collect the newest ads for a keyword or niche and study the hooks, formats and videos that keep running for months.
- Competitor monitoring: schedule a daily or weekly new-ads feed per competitor and get only their fresh launches.
- Audience and targeting research (EU): see which countries, ages and genders a competitor's ads actually reach in Europe, how big each campaign is, and which audience it was aimed at.
- Advertiser due diligence: find out who really paid for an ad and who benefits from it, as declared under EU rules.
- Lead generation: find businesses that advertise in your market, with their page links and landing pages.
- Political and issue ad tracking: collect political and issue ads with their paid-for-by name, spend and impressions ranges.
Also available
The Facebook and Meta suite: pick the job.
| Actor | Use when |
|---|---|
| Facebook Ads Library (this Actor) | Meta ads by keyword or advertiser |
| Google Ads Transparency | Ads an advertiser runs, by region |
| Facebook Pages | Page followers, contacts and latest post |
| Facebook Marketplace | Local listings by keyword, city and price |
| Instagram Profiles | Followers, bio and latest posts |
Quick Start
{"searchTerms": ["running shoes"],"country": "US","activeStatus": "active","maxItemsPerSearch": 50}
Every ad of one advertiser, in every country, running or stopped:
{"pageIds": ["15087023444"],"country": "ALL","activeStatus": "all","maxItemsPerSearch": 200}
A daily new-ads feed for a competitor and a keyword (schedule it in Apify; each run returns only ads that are new since the previous run):
{"pageIds": ["15087023444"],"searchTerms": ["running shoes"],"country": "US","onlyNewSinceLastRun": true,"monitorName": "competitors"}
Input
| Input | Type | Default | Meaning |
|---|---|---|---|
searchTerms | array | — | Keywords to search ad text for, as you would type them in the Ads Library search box. Each term is one search. |
pageIds | array | — | Advertiser IDs, exact page names such as Nike, or profile links such as facebook.com/nike, fb.com/nike and instagram.com/nike. Unknown or ambiguous names are skipped with a reason. Numeric IDs and profile.php?id=... links still work. |
adLibraryUrls | array | — | Search or advertiser links copied from facebook.com/ads/library. The filters inside a link are applied to that link (see Pasted Ads Library links). |
country | string | US | Two-letter country code where the ads were shown (US, GB, DE, BR...), or ALL for every country. |
activeStatus | string | active | active (running now), inactive (stopped) or all. |
mediaType | string | all | all, image, video, meme, image_and_meme or none (ads without an image or video). |
adCategory | string | all | all, political_and_issue_ads, housing_ads, employment_ads or credit_ads (financial products and services). |
keywordMatch | string | any_words | any_words (the Ads Library default) or exact_phrase. |
sortBy | string | most impressions | impressions (most impressions first, the Ads Library default) or newest (most recently started first). With onlyNewSinceLastRun, empty means newest. |
dateFrom, dateTo | string | empty | Only ads shown in this window: YYYY-MM-DD, or a period before today such as 7 days, 2 weeks or 1 month. An ad that started earlier and was still running inside the window counts, as on the Ads Library site. |
onlyNewSinceLastRun | boolean | false | Return only ads this actor has not delivered for the same search before. |
monitorName | string | empty | Optional name for a separate new-ads history, for example one per client. |
includeEuDetails | boolean | false | Also get each ad's EU transparency details: EU reach by country, age and gender, targeting, payer and beneficiary (see EU transparency details). |
maxItems | integer | empty | Optional total ad limit across all searches; empty means no extra run-wide limit. |
maxItemsPerSearch | integer | 100 | Stop each search after this many ads, up to 5,000. |
You can mix search terms, page IDs, names and links in one run. Ads already returned by an earlier search in the same run are not repeated.
Empty input runs a small example on its own: {} collects up to 10 ads for running shoes (US, active), and the status message and run summary (usedExample: true) say it was the example. Empty source lists use the same paid sample when there are no other sources or explicit limits. Nonempty lists containing only blank entries remain invalid. Add your own search to collect what you need instead.
New-ads feed
Turn on onlyNewSinceLastRun, keep the same searches, and schedule the run. The first run returns ads up to your limit and remembers them. Every later run returns only ads that are new since the previous run: ads it already delivered, and running ads that had already started before the previous run, are skipped and not charged. Results are read newest first unless you choose another sortBy, and a search stops once it reaches ads older than the previous run. Each search keeps its own history in your account; use monitorName to keep separate histories for the same search (for example per client). The run summary shows alreadySeen per search, and a search with nothing new reports NO_NEW_ADS.
EU transparency details
Turn on includeEuDetails and every ad that was shown in the EU also gets what the Ads Library's "See ad details" panel shows:
- Reach:
euTotalReach, the estimated number of people in the EU the ad reached, pluseuReachByCountry(largest first) andeuReachByCountryAgeGender(one row per country and age range, split by male, female and unknown). - Targeting:
euTargetedLocations,euTargetedGender,euTargetedAgeMinandeuTargetedAgeMax: the audience the advertiser chose. - Who is behind it:
payerandbeneficiary(every pair inpayerBeneficiary), as declared under EU rules. - UK too:
ukTransparencyholds the same reach and targeting data for the UK when Meta publishes it.
euDetailsStatus tells you what each row holds: present, or absent with a short euDetailsNote when the ad was not shown in the EU. You can search any country: a US search often returns ads that also ran in Europe. The Console's EU transparency view lists the key fields side by side.
{"searchTerms": ["running shoes"],"country": "FR","includeEuDetails": true,"maxItemsPerSearch": 50}
Pasted Ads Library links
A pasted link is reproduced exactly or skipped with an explanation. It is never turned into a broader search than the one you filtered, so you are never charged for rows you did not ask for.
| Link parameter | What the actor does |
|---|---|
country, active_status, media_type | Applied to that link; they override the form's values. |
q with search_type=keyword_unordered (the default) or search_type=keyword_exact_phrase | A keyword search for the term, any words or exact phrase. |
view_all_page_id with search_type=page | That advertiser's ads. |
ad_type (all, political_and_issue_ads, housing_ads, employment_ads, credit_ads) | Applied to that link. |
start_date[min], start_date[max] | The link's date window, applied to that link. |
is_targeted_country=false | Ignored: it is the Ads Library default and the value the actor already uses; any other value is refused. |
fbclid, ref, ref_id, locale, session_id, load_date, sort_data[...], the utm_source/utm_medium/utm_campaign/utm_term/utm_content/utm_id campaign keys and the usual share/tracking keys (mibextid, rdid, share_url, __cft__[...], __tn__) | Ignored: tracking, locale and display order cannot change which ads match. Use sortBy to choose the order. An unfamiliar key is refused rather than skipped as tracking. |
A link that carries one of these is skipped with the reason (in OUTPUT.skippedSearches and the status message) while the other searches still run; if it is the only entry the run ends green with OUTPUT.status: "no_results" and nothing is charged. What is refused, with what to change:
publisher_platforms[...]andcontent_languages[...]: remove them from the link, then filter the returned rows bypublisherPlatformsif needed;end_date[...]andexcluded_ids;is_targeted_countryset to anything butfalse;- any other parameter the actor does not know as a filter;
- an advertiser link that also carries a keyword (
q=), because this actor cannot combine a keyword with an advertiser link — paste the keyword as a search term instead; - a keyword
search_typeon a link withview_all_page_id, orsearch_type=pagewithout one; - a single-ad link (
?id=...); - the same filter twice with different values.
Example queries
{"searchTerms": ["meal kit", "protein powder"], "maxItemsPerSearch": 300}: up to 300 running US ads for each keyword.{"searchTerms": ["solar panels"], "country": "GB", "mediaType": "video", "sortBy": "newest"}: the newest video ads about solar panels shown in the UK.{"searchTerms": ["black friday sale"], "keywordMatch": "exact_phrase", "dateFrom": "7 days"}: ads with that exact phrase shown in the last week.{"searchTerms": ["election"], "country": "DE", "adCategory": "political_and_issue_ads", "activeStatus": "all"}: political and issue ads in Germany with spend and impressions ranges.{"searchTerms": ["sneakers"], "country": "DE", "includeEuDetails": true}: German sneaker ads with their EU reach by country, age and gender, targeting and payer.{"pageIds": ["15087023444"], "activeStatus": "all", "country": "ALL"}: the advertiser's full ad history across countries.{"adLibraryUrls": ["https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=DE&q=versicherung&search_type=keyword_unordered&media_type=all"]}: a search you set up on the site, pasted as is.
What it returns
The dataset contains one row per ad:
| Field | Meaning |
|---|---|
kind | ad for every dataset row. |
adArchiveId, adLibraryUrl | The Ads Library ID of the ad and its link in the Ads Library. |
pageId, pageName, pageProfileUrl, pageProfilePictureUrl | The advertiser's page. |
pageLikeCount, pageCategories | The advertiser page's likes and categories, as shown with the ad. |
partnerPage | On partnership (branded content) ads, the creator or brand the advertiser partnered with: pageId, pageName, pageProfileUrl, pageProfilePictureUrl, pageLikeCount, pageCategories, and adShownUnderPartner (true when the ad appears under the partner's name). null on other ads. |
isActive, startDate, endDate | Whether the ad is running, the date it started and the date it stopped (or the latest date it was seen running), YYYY-MM-DD. |
daysRunning | Days from startDate to endDate, counting both: long-running ads are usually the ones that work. |
publisherPlatforms | Where it runs: facebook, instagram, messenger, audience_network, threads, whatsapp. |
displayFormat | IMAGE, VIDEO, CAROUSEL, DCO (dynamic creative), DPA (product catalog) and so on. |
body, title, linkDescription, caption | The ad text, headline, link description and the domain shown on the ad. |
linkUrl, ctaText, ctaType | Where the ad leads and its call-to-action button. |
imageUrls, videoUrls | Every image and video link of the ad and its cards in one list each, ready to download. |
images | Image links, each with originalUrl and resizedUrl. |
videos | Video links, each with hdUrl, sdUrl and previewImageUrl. |
cards | Carousel and catalog cards, each listed once, each with its own title, body, linkUrl, linkDescription, caption, ctaText, ctaType and image or video links. |
extraTexts, extraLinks | Extra text variations and destination links the ad uses, when published. |
collationId, collationCount | Shared ID and count when several ads use the same creative. |
categories | Special ad categories (for example POLITICAL, HOUSING, EMPLOYMENT, CREDIT) when declared. |
containsSensitiveContent | Whether the Ads Library marks the ad as sensitive; null if not published. |
containsDigitalCreatedMedia | Whether the Ads Library labels the ad as containing digitally created or altered media (for example AI-generated). |
targetedOrReachedCountries | Countries the Ads Library lists for the ad, when it publishes them. |
pageIsDeleted | Whether the advertiser's page has since been deleted. |
spend, currency, impressions, reachEstimate | Ranges published for political and issue ads; empty for other ads. |
disclaimer | The paid-for-by name, when the ad carries one. |
searchTerm, searchPageId, searchCountry, searchUrl | The search this row came from. |
euDetailsStatus, euDetailsNote | Only with includeEuDetails: present (EU data below), absent (not shown in the EU), error (the details could not be read) or skipped (the run's time limit or maximum charge came first), with the reason in the note. |
targetsEu, euTotalReach, euReachByCountry, euReachByCountryAgeGender | Only with includeEuDetails: whether the ad was shown in the EU, its estimated EU reach, reach per country (country, reach) and per country and age range (country, ageRange, male, female, unknown). |
euTargetedLocations, euTargetedGender, euTargetedAgeMin, euTargetedAgeMax | Only with includeEuDetails: the audience the ad targeted; each location has name, type, excluded and numObfuscated. |
payer, beneficiary, payerBeneficiary | Only with includeEuDetails: who paid for the ad and who benefits, as declared under EU rules. |
ukTransparency | Only with includeEuDetails: UK reach and targeting (totalReach, reachByCountry, reachByCountryAgeGender, targetedLocations, targetedGender, targetedAgeMin, targetedAgeMax), or null. |
scrapedAt | Collection time (UTC). |
The run summary (OUTPUT) lists each search with the number of ads and pages returned and how it ended:
| Field | Meaning |
|---|---|
ads | Ads this search delivered, after removing ads an earlier search already returned. |
pages | Result pages it read. |
duplicates | Ads it matched that the run had already returned. |
complete | true only when the search reached the end of its results, so nothing is missing. |
stopReason | null when complete; otherwise maxItemsPerSearch (its own limit), maxItems (the run-wide limit), chargeLimit (your maximum charge), noNewAds (new-ads feed: it reached ads older than the previous run), safetyStop (the source stopped making progress), timeLimit (with includeEuDetails: the run stopped before its time limit to keep its rows) or error. |
error | NO_RESULTS (nothing matched), NO_NEW_ADS (everything it matched was already returned by an earlier search in this run, or, in a new-ads feed, nothing is new since the previous run), SAFETY_STOP, or the source's error code. A search stopped by a limit, a charge stop or an error before the end of its results leaves error empty rather than claim its matches were all delivered; stopReason says what stopped it. |
alreadySeen, startedBeforeLastRun | New-ads feed only: ads skipped because an earlier run delivered them, or because they were already running before the previous run. |
outsideDateRange | With a date window: ads skipped because they ran outside it. |
With includeEuDetails, OUTPUT.euDetails counts the delivered ads by EU status (requested, present, absent, errors, skipped).
OUTPUT.searchesComplete and OUTPUT.searchesIncomplete count the searches that reached the end of their results and those stopped by a limit, a charge stop, a new-ads stop, a safety stop or an error. OUTPUT.stoppedBy records the run-wide reason, and OUTPUT.skippedSearches lists searches not attempted plus any entry that could not be run as the search you gave (each with its input, stopReason and reason); none of them are charged. OUTPUT.status is complete when ads were delivered (skipped entries are still listed in OUTPUT.skippedSearches), or no_results when nothing matched, nothing was new since the last run, or every entry had to be skipped; noResultsReason says which. OUTPUT.usedExample is true when empty input ran the prefilled example search. Searches that failed or stopped early are also listed in OUTPUT.searchErrors with the number of ads they delivered before stopping. After three searches in a row are refused or slowed down without returning ads, or when the run cannot renew access, it stops.
Output example
{"kind": "ad","adArchiveId": "1702938977100376","adLibraryUrl": "https://www.facebook.com/ads/library/?id=1702938977100376","pageId": "15087023444","pageName": "Nike","pageProfileUrl": "https://www.facebook.com/nike/","pageProfilePictureUrl": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/431756959_712871054375981_n.jpg","pageLikeCount": 39500444,"pageCategories": ["Sportswear","Product/service"],"partnerPage": null,"isActive": true,"startDate": "2025-04-07","endDate": "2026-10-19","publisherPlatforms": ["facebook","instagram","audience_network","messenger"],"displayFormat": "DPA","body": "Bring sports more fully into your day with the Nike App.","title": "{{product.name}}","linkUrl": "http://itunes.apple.com/app/id1095459556","linkDescription": null,"caption": "itunes.apple.com","ctaText": "Install now","ctaType": "INSTALL_MOBILE_APP","images": [],"videos": [],"cards": [{"title": "Nike Run Swift 3 Women's Road Running Shoes","body": "Bring sports more fully into your day with the Nike App.","linkUrl": "https://www.nike.com/ph/t/run-swift-3-road-running-shoes-2fHbzp/DR2698-002","linkDescription": "₱3,995","caption": "itunes.apple.com","ctaText": "Install Now","ctaType": "INSTALL_MOBILE_APP","originalImageUrl": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/431679131_949214166636263_n.jpg","resizedImageUrl": "https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/431679131_949214166636263_s600x600.jpg","videoHdUrl": null,"videoSdUrl": null,"videoPreviewImageUrl": null}],"collationId": null,"collationCount": null,"categories": [],"containsSensitiveContent": false,"spend": null,"currency": null,"impressions": null,"reachEstimate": null,"disclaimer": null,"daysRunning": 561,"targetedOrReachedCountries": [],"containsDigitalCreatedMedia": false,"pageIsDeleted": false,"imageUrls": ["https://scontent-phl2-1.xx.fbcdn.net/v/t39.35426-6/431679131_949214166636263_n.jpg"],"videoUrls": [],"extraTexts": [],"extraLinks": [],"searchTerm": null,"searchPageId": "15087023444","searchCountry": "ALL","searchUrl": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=ALL&media_type=all&search_type=page&view_all_page_id=15087023444","pageInstagramUsername": null,"pageInstagramFollowers": null,"pageInstagramVerified": null,"pageVerification": null,"pageCategory": null,"pageAbout": null,"pageCreationDate": null,"scrapedAt": "2026-10-20T05:41:00+00:00"}
Image and video links are shortened here; real links are longer and expire after some days, so download media you want to keep soon after the run.
Good to know
- Results come in the order you choose with
sortBy(most impressions by default). A run capped bymaxItemsPerSearchormaxItemsreturns the first ads in that order. Keyword searches match ad text, so broad words return many advertisers;exact_phrasenarrows them. - Newest first is the Ads Library's own "most recent" order: recently started ads come first, grouped by month, not strictly by day.
titleandbodyof catalog ads (DPA) can hold placeholders such as{{product.name}}; the real product names are incards.- On a partnership ad shown under the creator's name, the Ads Library shows the creator's likes and categories, not the advertiser's: those go to
partnerPage, and the advertiser'spageLikeCount,pageCategoriesandpageProfilePictureUrlare empty for that ad. - Spend, impressions and reach ranges are only published by the Ads Library for political and issue ads (and some regulated regions); they are empty otherwise. For ads shown in the EU, turn on
includeEuDetailsfor EU reach, targeting and payer. - EU transparency details are Meta's own estimates, copied as published. Meta publishes them only for ads delivered in the EU (and the UK); other ads get
euDetailsStatus: "absent"and a note. Each ad needs one extra lookup, so runs withincludeEuDetailstake longer. If one lookup fails the ad row is still delivered, markederror. Near the run's time limit the run stops early and keeps what it collected (OUTPUT.stoppedBy: "timeLimit"); raise the timeout for large runs. - Advertisers are found by page ID or link; a page name alone (for example
facebook.com/nike) is not looked up. Open the advertiser in the Ads Library and copy the link instead. - Ads already returned by an earlier search in the same run are skipped, so overlapping searches do not return duplicates. A search keeps paging past those duplicates and still reaches its later new ads.
- If the source keeps repeating a page, or keeps serving ads outside your date window, that search stops as
SAFETY_STOPwithcomplete: falseinstead of claiming it finished. - If a search stops early, the ads it already returned are kept and the reason is shown in the run summary. If no search returns any ad because of an error, the run fails with a clear message instead of finishing empty. A search with no matching ads is reported in the run summary as no results and is not charged.
maxItemsPerSearchgoes up to 5,000 ads per search. Large searches take a few minutes per thousand ads.- Automated access is subject to Meta's terms; use this actor only where you have the necessary permissions and a lawful basis.
FAQ
Is this a Facebook Ad Library API? It gives you the same ads you see in the Meta Ad Library, as rows you can export to JSON, CSV or Excel or read through the Apify API, for every ad category and every country, without a Facebook account or developer app.
How do I see a competitor's newest ads? Put their page ID or Ads Library link in pageIds or adLibraryUrls, set sortBy to newest, and keep maxItemsPerSearch small. For ongoing tracking, turn on onlyNewSinceLastRun and schedule the run.
How do I list every ad of one advertiser? Paste the numeric page ID into pageIds (the number after view_all_page_id= in an Ads Library link), or paste the advertiser link itself into adLibraryUrls. Set country to ALL and activeStatus to all for the full history.
Why did I get fewer ads than my limit? A search stops when the Ads Library reaches the end of its results for that keyword or advertiser, and a search with no matches returns zero ads and is not charged. Narrow or misspelled words can match nothing; in a new-ads feed, a quiet day returns few or no ads.
Why are spend, impressions and reach empty? The Ads Library publishes those ranges only for political and issue ads (and some regulated regions). Set adCategory to political_and_issue_ads to collect those ads. For ads shown in the EU, includeEuDetails adds EU reach by country, age and gender.
How do I get EU reach, targeting and the payer? Turn on includeEuDetails. Every ad that ran in the EU gets its EU reach, the breakdown by country, age and gender, its targeting and the declared payer and beneficiary. Ads that did not run in the EU are marked absent with a note.
Why did an image or video link stop working? Media links are signed and expire after some days. Download the media you want to keep soon after the run.
What does empty input do? It runs the example search (running shoes, US, active ads, up to 10) so a first run shows real rows immediately; the status message and OUTPUT.usedExample say it was the example. A nonempty search term, page ID or link uses your own source. Empty source lists use the same paid sample without explicit limits; a limit alone still requires a real source.
What does a failed search cost? Nothing. Searches that fail or return no matches are not charged, ads skipped by the new-ads feed or the date window are not charged, and the run summary is free; only delivered ads are billed.
Pricing
$0.0015 per ad returned plus a $0.00125 start event per run; from 24 November 2026 the ad price is $0.0025 per ad (already scheduled on the Pricing tab, which always has the current rates). The start event is charged per GB of memory, so the default 2048 MB run is two start events. Optional EU transparency details are included at no extra charge for now.
What a run costs: the Console's sample input (one keyword search, up to 50 ads) returns up to 50 rows, about $0.078 in total — $0.075 in ad charges plus the $0.0025 start ($0.128 from 24 November). A smaller first run with maxItemsPerSearch: 10 costs about $0.018. A daily new-ads feed only pays for the new ads it finds. Start with a small maxItemsPerSearch and check the run cost before scheduling larger collections.
Advertiser page information
Every ad row includes nullable pageInstagramUsername, pageInstagramFollowers,
pageInstagramVerified, pageVerification, pageCategory, pageAbout and
pageCreationDate. A name or profile-link search supplies the advertiser information
returned by the page lookup. With includeEuDetails, the existing detail answer can
also supply About text and page information. Numeric-ID and keyword searches leave
these fields null when the ad itself does not include them. Missing counts stay null;
creation date is unavailable in the public answers checked so far.
OUTPUT.searches[].totalAdCount is the source's total when it includes one,
otherwise null. This does not estimate a total from the number of ads collected.
When the run reaches its time budget it keeps the ads already saved and succeeds;
stoppedBy and the search's stopReason retain timeLimit, and
OUTPUT.stopReason also reports time-limit. Raise the run timeout to collect more.