Facebook Ads Library Scraper avatar

Facebook Ads Library Scraper

Pricing

from $0.04 / 1,000 ads

Go to Apify Store
Facebook Ads Library Scraper

Facebook Ads Library Scraper

Scrape the Meta Ad Library (Facebook, Instagram, Messenger, Threads) by keyword, advertiser, ad ID or URL in any country: ad text, media, links, dates, platforms, spend and EU audience. No login. Export to JSON, CSV or Excel.

Pricing

from $0.04 / 1,000 ads

Rating

0.0

(0)

Developer

Nice Dev

Nice Dev

Maintained by Community

Actor stats

0

Bookmarked

6

Total users

2

Monthly active users

10 days ago

Last modified

Features

Limited permissions

Share

📣 What is Facebook Ads Library Scraper?

Facebook Ads Library Scraper extracts ads from the Meta Ad Library — the ads that run on Facebook, Instagram, Messenger, Audience Network and Threads: ad text, headline, images and videos, link and button, start and end dates, days running, platforms, advertiser page, and for political and issue ads the spend, impressions and audience. Search by keyword, by advertiser (name, page link or page ID), by ad ID or with any Ad Library URL, in one country or many. It works as a Facebook Ad Library API alternative: no developer account or access token, every kind of ad, and you can run it on a schedule, call it from your code, or plug it into Make, Zapier or n8n — for competitor ad research (ad spy), creative inspiration, market sizing or political ad monitoring.

Type a keyword (running shoes) or an advertiser (Nike), pick a country, click Start, and download the ads in JSON, CSV or Excel. No Facebook account, no cookies, nothing to set up: in our tests, one search returned 1,000 ads in under 5 minutes. Extra data (EU audience and payer, advertiser profile, page owner, all versions, final landing page, contacts, saved media) are options, off by default, that you pay only when you tick them.

📋 What data can you extract from the Meta Ad Library?

One item per ad, 99 fields:

CategoryWhat you get
🏷️ AdAd Library ID, link to the ad, running or stopped, ad category (political, housing, employment…), group of identical ads and how many versions it has
🏢 Advertiserpage name, page ID, page link, profile picture, page categories, page likes, deleted page, "Paid for by" line — Lost Dutchman Leather Goods
📝 Creativeheadline, ad text, caption, link description, button (Shop now), format (image, video, carousel, catalog, dynamic), every card of a carousel or catalog ad, dynamic texts, branded-content partner, the full creative object as Meta returns it
🖼️ Images and videosevery image and video link (HD and SD, preview image); the text written in the images (option)
🔗 Linkthe URL the ad points to, its domain, its UTM tracking parameters — lostdutchmanleather.com
🕒 Datesstart date, end date, days running (826), total active time
📱 Platforms and countriesFacebook, Instagram, Messenger, Audience Network, Threads; the countries the ad targeted or reached
💰 Spend and reach (political and issue ads)amount spent as Meta prints it ($600K - $700K) with its lower and upper bounds, currency, impressions range (>1M), estimated audience size
🛡️ Transparency labelssensitive content, digitally created or AI-altered media, state-controlled media, EU transparency eligibility, reports
🔎 Searchkeyword, country, advertiser and URL of the search that found the ad, and how many ads the Ad Library has for that search
🇪🇺 Ad details (option)who paid and who benefits, and for ads shown in the EU, UK or Brazil the audience Meta publishes: total EU reach, targeted locations, gender and ages, reach by country, age and gender
👤 Advertiser profile, owner and audience (options)Instagram account and followers, verification badges, total spend on political ads; the confirmed page owner (name, address, phone when published), page creation date, name changes, countries of the page managers; the advertiser's ad count, spend and targeting over 7, 30 or 90 days
🛬 Landing page and contacts (options)final landing URL after redirects, page title, product name, price, brand, availability and rating; e-mails, phone numbers, social links and shop platform (Shopify, WooCommerce…) of the landing page
🔁 Versions and saved media (options)every version of a grouped ad with its dates, platforms and text; images and videos saved in your run's storage, where Meta's links do not expire

Every field, with an example, is listed in the Output section below.

The four last rows, and the text written in the images, are filled only when their option is ticked (all off by default, each charged only when it returns data). The image and video links Meta gives expire after a few days: tick Save images and videos to keep the files.

✅ Why use Facebook Ads Library Scraper?

  • 🔎 Every way in, in one run: keywords, advertisers by name, page link or page ID, single ads by ID, or any Ad Library URL you paste — searched in as many countries as you want.
  • 🎛️ All the Ad Library filters in the form, plus the ones Meta lacks: how long an ad has run, how many versions it has, creative format, link domains, advertisers and words to exclude, delivery dates.
  • 🕵️ Competitor ads, complete: the advertiser's EU audience and payer, page owner, audience and spend, all versions of a creative, the real landing page and its product, the contacts of the landing page — each as an option you tick only when you need it.
  • 🔔 Monitoring built in: tick Only new ads, schedule the Actor, and each run returns only what it has never delivered before (an ad it reads again costs one small filter check).
  • 🧩 Nothing twice: pagination is automatic, an ad found by several searches is saved once, and searchCountry tells which country found it.
  • 📊 Market sizing: Totals only returns how many ads the Ad Library has for each keyword, advertiser and country, without reading the ads.
  • 🔌 API, scheduling, integrations (Make, Zapier, n8n, Google Sheets…) and JSON/CSV/Excel export via the Apify platform.

🚀 How to scrape the Meta Ad Library

  1. Create a free Apify account.
  2. Open Facebook Ads Library Scraper, type a Search keyword (e.g. running shoes) or fill Advertisers by name (e.g. Nike), and pick a Country.
  3. Or paste your own Ad Library URLs into Ad Library URLs or advertiser pages: a search (all filters set on the site are kept, pagination is automatic), an advertiser's ads, a single ad or a Facebook page.
  4. Set Max ads (100 by default, 0 = no limit) — and Max ads per search when you run several searches — then click Start.
  5. Download the dataset in JSON, CSV, Excel or via API.

💰 How much does it cost to scrape the Meta Ad Library?

This Actor uses pay per event pricing: you pay for each ad saved, plus a small fee per run start. Higher Apify plans pay less per ad; the prices of each plan are shown in the Pricing tab. Each option adds its own price, and only when it returns something:

  • Ad details: per ad delivered with its details.
  • Advertiser info, Page transparency: once per advertiser and per run.
  • Advertiser audience and spend: once per advertiser and per run, and only when Meta publishes the audience (an empty one is not charged).
  • All versions of grouped ads: per grouped ad read (an ad alone in its group costs nothing more).
  • Final landing page: per distinct link followed (ads that share a link, tracking parameters aside, are charged once; an ad without a link costs nothing more).
  • Contacts and shop platform of the landing page: per website where something is found, once per run (the other ads of that website carry the same contacts at no extra charge; the links of a link shortener count one by one).
  • Save images and videos: per started 3 MB of each file saved (an image counts once, a 60 MB video 20 times; a file that could not be saved is not charged).
  • Totals only: per search, for its row of totals.
  • Market statistics: per search summary delivered (a search with fewer than 10 ads has none and costs nothing).
  • AI image text: per image in which readable text is found (an image without text costs nothing; up to 10 images per ad).
  • AI speech in videos: per ad video in which speech is found (music only, no sound or no video costs nothing more).
  • AI labels: per label judged on an ad written in English (an ad in another language or without text costs nothing more).
  • Ad score: per ad scored (an ad without a start date has no score and costs nothing more).

The filters Meta does not apply itself, or not exactly (start and delivery dates, days running, versions, formats, domains, excluded advertisers and words), are checked by the Actor on every ad it reads: an ad you keep costs its normal price, an ad a filter drops costs a small filter fee instead. Platform usage (compute, proxy) is included in the price.

⚙️ Input

{
"query": "running shoes",
"country": "US",
"maxItems": 200
}

Competitor research: two advertisers in two countries, active and stopped ads that ran at least 30 days, with the advertiser's profile:

{
"advertiserNames": ["Nike", "Adidas"],
"countries": ["FR", "DE"],
"activeStatus": "all",
"minDaysRunning": 30,
"maxItemsPerQuery": 100,
"includeAdvertiserInfo": true
}

Your own Ad Library URLs (a search and a single ad):

{
"startUrls": [
{
"url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=shoes&search_type=keyword_unordered"
},
{ "url": "https://www.facebook.com/ads/library/?id=1563512104518420" }
],
"maxItems": 500
}

Monitoring one advertiser, only the ads not delivered before, with their images and videos saved:

{
"pageIds": ["15087023444"],
"onlyNew": true,
"stateKey": "nike-ads",
"downloadMedia": true
}

Market sizing: how many ads two keywords have in three countries, without reading the ads:

{
"searchQueries": ["protein powder", "creatine"],
"countries": ["US", "GB", "DE"],
"onlyTotalCount": true
}
FieldNotes
startUrlsLinks from the Meta Ad Library: a search (https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=shoes&search_type=keyword_unordered, every filter set on the site is kept, pagination is automatic), an advertiser's ads (…&view_all_page_id=<page id>), a single ad (https://www.facebook.com/ads/library/?id=<ad id>) or a Facebook page (https://www.facebook.com/nike). Max 1 000 URLs. The search fields below are added to them.
query, searchQueries, exactPhraseWords searched in the ads' text, as typed in the Ad Library search box (running shoes); searchQueries adds more keywords, one search each; exactPhrase matches them as an exact phrase.
pageIdsAll the ads of these advertisers: page ID (15087023444), page link (https://www.facebook.com/nike) or the last part of the link (nike). Max 1 000.
advertiserNamesAdvertiser names as shown in the Ad Library (Nike, Decathlon France) or Instagram accounts (@thedemocrats): the best match is read (exact page name, alias or Instagram account first, then the most liked page), and the page found is returned with each ad (searchPageId). Max 100.
adIdsSingle ads by their Ad Library ID (1234567890123456, the id= of an ad link), read in every country and status. Max 1 000.
countryCountry where the ads were shown (US, FR); ALL (the default) covers the whole library.
countriesMore countries: every keyword and advertiser is searched in every country (max 1000 searches per run). Two-letter codes (FR, DE) or ALL; searchCountry tells which country found the ad.
maxItems, maxItemsPerQuerymaxItems: most ads saved for the whole run, after deduplication and filters (0 = no limit). maxItemsPerQuery: cap for EACH search (keyword × country, advertiser × country, or pasted URL), 0 = no per-search cap.
activeStatusactive (default), inactive or all.
adTypeALL (default) or one of the Ad Library's categories: POLITICAL_AND_ISSUE_ADS (Issues, elections or politics: these come with spend, impressions and audience), HOUSING_ADS, EMPLOYMENT_ADS, CREDIT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS, UNCATEGORIZED_ADS.
mediaTypeall (default), image, video, meme, image_and_meme or none.
publisherPlatformsOnly ads shown on at least one of these platforms: facebook, instagram, messenger, audience_network, threads. Empty = all.
contentLanguagesOnly ads written in these languages, as two-letter codes (en, fr, es). Empty = all.
sortByimpressions (most impressions first, the site's default) or newest. It matters with a cap.
isTargetedCountryOnly ads that TARGETED the chosen country, not the ones that merely reached people there.
bylinesOnly political and issue ads whose "Paid for by" line is exactly one of these names (WALMART INC.).
postedAfter, postedBeforeStart date range: a date (2026-09-01, the whole day included) or a period before now (7 days, 2 weeks, 1 month; via the API also 24 hours). Reads the ad's start date.
deliveredAfter, deliveredBeforedeliveredAfter: still running on or after this date (2026-09-01 or 30 days). deliveredBefore: stopped on or before it (an ad still running is dropped: needs Ad status set to inactive or all, else the input is refused). Together: the ads that ended inside a period.
minDaysRunning, maxDaysRunningDays from the start date to the end date (to today for an active ad): 30 keeps the long-running ads, usually the ones that sell; 0 = no bound.
minCollationCountOnly ads whose group has at least this many versions (3): advertisers test and scale the creatives that work. 0 = no minimum.
displayFormatsOnly these creative formats: IMAGE, VIDEO, CAROUSEL, DPA (catalog), DCO (dynamic). Empty = all.
includeDomains, excludeDomainsKeep, or drop, the ads whose link, caption or a card's link goes to one of these domains (gymshark.com also matches fr.gymshark.com).
excludePageIdsDrop the ads of these advertisers: page ID, page link or the last part of the link (nike) — e.g. your own brand in a keyword search.
excludeKeywordsDrop the ads whose text (body, title, caption, link description or a card's text) contains one of these words (giveaway) as a whole word (cat keeps "category"), case and accents ignored; a word in Chinese, Japanese, Korean, Thai, Burmese, Khmer or Lao is found anywhere in the text.
includeAdDetailsPaid option, off by default: who paid for the ad and who it is for, and for ads shown in the EU, UK or Brazil the audience Meta publishes (EU reach, targeted locations, gender, ages, reach by country, age and gender).
includeAdvertiserInfoPaid option, off by default: Facebook likes, Instagram account and followers, verification badges, page category, about text and the amount spent on political ads, once per advertiser.
includePageTransparencyPaid option, off by default: the About tab of the advertiser — confirmed page owner, page creation date, name changes, countries of the page managers, related pages — once per advertiser.
includeAdvertiserAudience, audienceTimeframePaid option, off by default: the advertiser's Audience tab over LAST_7_DAYS, LAST_30_DAYS (default) or LAST_90_DAYS — number of ads, amount spent, targeting by gender, age, location, custom and lookalike audiences and language, with the share of spend of each. Published by Meta for advertisers of political and issue ads; others are not charged.
includeAdVersionsPaid option, off by default: every version of an ad that the Ad Library groups with others, with its dates, platforms and text. Ads alone in their group cost nothing more.
resolveLandingPagesPaid option, off by default: follows each ad's link through its redirects and tracking links to the final page (URL without tracking, status, title, and for a product page its name, price, brand, availability and rating).
downloadMedia, maxMediaPerAdPaid option, off by default: saves the ad's images and videos (cards included) in the run's storage, as Meta's links expire after a few days; at most 10 files per ad by default (1 to 50), videos over 200 MB skipped.
extractLandingContactsPaid option, off by default: e-mails, phone numbers, social links and shop platform (Shopify, WooCommerce, Wix…) found on each ad's landing page, once per domain (once per app for an app store) — a lead list from the advertisers of a search.
includeMarketStatsPaid option, off by default: at the end of the run, one summary per search with at least 10 ads delivered, in the MARKET_STATS record of the key-value store (not in the dataset). Cannot be combined with Totals only.
imageTextPaid option, off by default: AI reads the text written in each ad's images (offer, dates, brand, button) into the two image text columns (see Output); Latin-script text only; needs 2 GB of memory. Cannot be combined with Totals only.
videoTranscriptPaid option, off by default: AI writes down what is said in the ad's main video (first 60 seconds of sound) into the video transcript and video language columns (see Output). Music only or no sound = empty and free. Needs 2 GB of memory. Cannot be combined with Totals only.
aiLabelNamesPaid option, off by default: your own labels (up to 20, in English: discount, free shipping, testimonial; write name: what it means to say more). AI judges the English text of each ad and adds aiLabels (a score and a match per label). Only ads written in English are labelled. Needs 2 GB of memory. Empty list = off. Cannot be combined with Totals only.
includeAdScorePaid option, off by default: a 0-100 "winning ad" score for each ad (adScore), with the points of each factor (adScoreFactors): how long it has been running, how many versions it has, its platforms, its countries and whether it is still active. Computed on the ad's own data, no extra request. Cannot be combined with Totals only.
onlyTotalCountOne row per search with the number of ads the Ad Library has for it, without reading the ads. Cannot be combined with the ad options above.
stateKey, onlyNew, resetStateMonitoring: onlyNew skips the ads already delivered under this memory key (competitor-ads-fr; letters, digits, dashes and underscores); resetState forgets the memory before the run.
runTagAny label (client-a-weekly), copied into every row to tell your runs apart.
AdvancedproxyConfiguration (keep Apify Proxy, the default: the Actor picks the connection each page needs, included in the price; with your own proxy URLs every request goes through them), maxConcurrency, maxRequestsPerMinute, minRequestIntervalMs, maxRequestRetries, debugLog.

📦 Output

One real ad from a search for nike in France (shortened: long texts and media links cut, and most columns that are empty for this ad left out):

{
"recordType": "ad",
"id": "1563512104518420",
"url": "https://www.facebook.com/ads/library/?id=1563512104518420",
"pageId": "381727498962869",
"pageName": "Lost Dutchman Leather Goods",
"pageUrl": "https://facebook.com/lostdutchmanleather",
"pageCategories": ["Accessories"],
"pageLikeCount": 139044,
"isActive": true,
"status": "ACTIVE",
"startDate": "2024-07-17T07:00:00.000Z",
"endDate": "2026-10-21T07:00:00.000Z",
"daysRunning": 826,
"publisherPlatforms": ["FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER"],
"collationId": "1157358358844275",
"collationCount": 1,
"displayFormat": "VIDEO",
"title": "🌵Upgrade Your Everyday Carry",
"bodyText": "Considerately designed & crafted for perfection. Each piece ages uniquely to the owner, meaning no two pieces will patina the same.",
"caption": "www.lostdutchmanleather.com",
"linkUrl": "https://www.lostdutchmanleather.com/collections/all",
"landingDomain": "lostdutchmanleather.com",
"ctaText": "Shop now",
"ctaType": "SHOP_NOW",
"videoUrl": "https://video.fnap7-1.fna.fbcdn.net/o1/v/t2/f2/m412/AQMOPBRiXSyfL5j2VFJ70W98domNTzuti97JYH-EwsL9xuYTV6t6O53_jHU_E70QxIY69gIa4H6tYWqKs4dtmyCa.mp4",
"spend": null,
"impressionsIndex": -1,
"containsDigitalCreatedMedia": false,
"searchQuery": "nike",
"searchCountry": "FR",
"searchUrl": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=FR&q=nike&search_type=keyword_unordered",
"totalCount": 6318,
"adDetails": null,
"versions": null,
"savedMedia": null,
"imageText": null,
"imageTexts": null,
"videoTranscript": null,
"videoLanguage": null,
"videoDuration": null,
"aiLabels": null,
"adScore": null,
"adScoreFactors": null,
"scrapedAt": "2026-10-21T12:00:00.000Z"
}

You can download the dataset in various formats such as JSON, HTML, CSV or Excel.

All 99 fields

FieldsWhat you get
recordTypead, or searchTotal for the row of a search with Totals only
id, adArchiveId, adIdAd: the Ad Library ID (1563512104518420), twice, and Meta's internal ad ID when the site gives it
url, adLibraryUrllink to the ad in the Ad Library
pageId, pageName, pageUrl, pageProfilePictureUrlAdvertiser: page ID, name, link, profile picture
pageCategories, pageLikeCount, pageIsDeletedpage categories, likes shown on the ad, deleted page
byline, disclaimerLabel"Paid for by" line of political ads, disclaimer shown on the ad
isActive, statusrunning now, ACTIVE or INACTIVE
startDate, endDate, startDateUnix, endDateUnixDates: ISO 8601 UTC and Unix seconds; for an active ad, the end date is the last day seen running
daysRunning, totalActiveTimedays from start to end (to today for an active ad), total active time in seconds as the site gives it
publisherPlatforms, categoriesFACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, THREADS; Ad Library categories (POLITICAL, HOUSING…)
collationId, collationCountgroup of identical ads and its number of versions
displayFormatIMAGE, VIDEO, CAROUSEL, DPA (catalog), DCO (dynamic)
title, bodyText, caption, linkDescriptionCreative: headline, ad text, caption, text under the headline
linkUrl, landingDomain, utmParametersLink: URL, domain without www., tracking parameters as an object
ctaText, ctaTypebutton text and type (Shop now, SHOP_NOW)
imageUrl, imagesfirst image, every image (original, resized, watermarked)
videoUrl, videoPreviewImageUrl, videosfirst video (HD when available), its preview, every video (HD, SD, watermarked)
cards, cardCountcarousel and catalog cards (title, text, link, button, image and video of each)
extraTexts, extraLinks, extraImages, extraVideosother texts, links, images and videos of a dynamic ad
isReshared, brandedContentthe ad reshares a post; branded-content partner
countryIsoCode, targetedOrReachedCountriescountry shown on the ad, countries the ad targeted or reached
currency, spend, spendLower, spendUpperSpend (political and issue ads): the amount as Meta prints it ($600K - $700K), its bounds (600000, 700000)
impressionsText, impressionsLower, impressionsUpper, impressionsIndeximpressions as shown (>1M, 10K-15K), their bounds, the site's index (-1 = none)
reachEstimateestimated audience size as Meta prints it (>1M)
containsSensitiveContent, containsDigitalCreatedMedia, stateMediaRunLabelTransparency labels: sensitive content, digitally created or altered media, state-controlled media
gatedType, isAaaEligible, hasUserReported, reportCount, hideDataStatusvisibility gate, EU ad transparency eligibility, reports, hidden data
regionalRegulationData, menuItems, fevInforegional rules (financial services, Taiwan anti-scam) and other data the site gives
searchQuery, searchCountry, searchPageId, searchUrl, totalCountSearch that found the ad first: keyword, country, advertiser, URL, number of ads the Ad Library has for it. For an advertiser given by name, searchUrl holds the name typed and names the search; that advertiser's ads are at https://www.facebook.com/ads/library/?view_all_page_id=<searchPageId>
snapshotthe ad's full creative object as Meta returns it (snake_case)
adDetails, payer, beneficiary, euTotalReachAd details (option): payer, beneficiary, targetsEu, euTotalReach, targetLocations, targetGender, targetAges, reachBreakdown (by country, age and gender), UK and Brazil transparency; for political ads ageGender, regions; moderation flags
advertiserAdvertiser info (option): likes, igUsername, igFollowers, igVerified, pageVerification, pageCategory, pageAlias, about, lifetimeSpend and weeklySpend by "Paid for by" label…
pageTransparencyPage transparency (option): confirmedOwner (name, address, phone), createdAt, nameChanges, adminCountries, relatedPages…
advertiserAudienceAdvertiser audience (option): totalAds, totalSpend, gender, age, locations, customAudiences, lookalikeAudiences, languages with their share of spend; filled: false when Meta publishes nothing (not charged)
versionsAll versions (option): ID, link, dates, platforms, format, texts and media of each version; [] for an ad alone in its group
landingPageFinal landing page (option): finalUrl, finalDomain, statusCode, redirects, title, metaDescription, product (name, price, currency, brand, availability, rating)
savedMediaSaved media (option): for each file type, sourceUrl (Meta's expiring link), url (link in the run's storage), contentType, bytes; [] = the ad has no media
landingContactsLanding page contacts (option): emails, phones, socialLinks, shopPlatform, pageUrl
imageText, imageTextsAI image text (option): the text found in the main image, and in every image (main image, other images, carousel cards, video preview; up to 10 per ad), in the same order; null for an image without readable text
videoTranscript, videoLanguageAI speech in videos (option): what is said in the first minute of the ad's main video, and its language code (en, fr…); null for an ad without video, a video with music only or no sound, or when the option is off
videoDurationAI speech in videos (option): length in seconds of the ad's main video; also filled when the video has no speech (nothing charged then); null for an ad without video, an unreadable video file, or when the option is off
aiLabelsAI labels (option): one entry per label asked, in the order of the input: label, score (0 to 1) and match (true or false); null for an ad not in English, without text, or when the option is off
adScore, adScoreFactorsAd score (option): the 0-100 "winning ad" score, and the points of each factor: longevity (0-40), versions (0-25), platforms (0-15), countries (0-10), active (0-10); null for an ad without a start date, or when the option is off
runTag, scrapedAtthe Run tag of the input, when the ad was read

Every column is always there, except in the row of Totals only (8 columns): a value the site does not give, or an option not ticked, is null.

💡 Tips

How to get more results

Set Max ads to 0, choose ALL in Ad status and add countries: each keyword or advertiser is searched in each country. Political and issue ads are listed in every country; other ads only where the law makes Meta list them (EU, UK, Brazil…) or where they are running now — so stopped commercial ads are best searched in an EU country.

How to reduce costs

The price is per ad, so the levers are Max ads, Max ads per search, the filters the Ad Library applies itself (status, category, media type, platforms, languages, "Paid for by": nothing is charged for what they leave out) and Only new ads for recurring runs (you never pay the full price twice for the same ad; one a run reads again costs a filter check). Tick an option only when you need its data. To know how big a search is before reading it, run it with Totals only.

Spy on a competitor's ads

Put the brand in Advertisers by name (Nike) or Advertisers (page link or ID), set Ad status to all and Min days running to 30: the ads still running after a month are usually the ones that work. Min versions keeps the creatives the advertiser has scaled; All versions of grouped ads returns every variant. Final landing page and Contacts and shop platform of the landing page show where the traffic goes.

Several searches in one run

Fill searchQueries, pageIds, advertiserNames and / or countries: the Actor runs one search per keyword × country and per advertiser × country (3 keywords × 4 countries = 12 searches, up to 1000 per run). A single Search keyword and Country are added to the lists. An ad found by several searches is saved — and charged — once, with the first search that found it. Set Max ads per search to give every search its own cap: without it the first searches can use up the whole Max ads budget. Pasted URLs are searches of their own, with the same cap.

Monitoring: only the new ads

Tick Only new ads (onlyNew) and schedule the Actor. The first run returns everything; each later run skips the ads already delivered: they are not saved again; each one a run reads again costs one filter check (Meta's "newest" order is not by date, so a run reads them to find the new ones). The memory lives in a named key-value store of your account (facebook-ads-library-scraper-seen, up to 150,000 ads per key) and is only updated with ads that really reached the dataset, so a failed run never hides anything. Give each schedule its own stateKey (two schedules sharing a key would hide each other's ads), and tick resetState once to start over. The Ad Library does not list ads strictly by date, so each search is read up to its cap or its end.

The filters postedBefore, deliveredBefore, minDaysRunning and minCollationCount can let an ad through later (it gets older, stops running, or gains versions): with Only new ads, an ad they drop is checked again at the next runs, and each check costs the filter fee.

Filter by date and by how long ads ran

postedAfter and postedBefore read the ad's start date; deliveredAfter and deliveredBefore its end date (today for an active ad). Each takes a date (2026-09-01, the whole day is included, UTC) or a period before now (7 days, 2 weeks, 1 month; via the API also 24 hours or a full ISO date-time). postedAfter and postedBefore are also sent to the Ad Library, which then returns mostly the ads of that period. minDaysRunning and maxDaysRunning count the days from start to end. Filtered-out ads are not saved and do not count in Max ads (each ad dropped costs the filter fee, see Pricing); the run summary tells how many were filtered.

Keep the images and videos

The image and video links Meta gives (imageUrl, videoUrl, images, videos, pageProfilePictureUrl) expire after a few days. Tick Save images and videos (downloadMedia): each file is saved in the run's key-value store and its link written in savedMedia, up to Max media files per ad (10 by default). A file is charged per started 3 MB (an image counts once, a 60 MB video 20 times), so the price follows the weight you keep in your storage.

Size a market with Totals only

Tick Totals only (onlyTotalCount) with many keywords, advertisers and countries: one row per search with totalCount, the number of ads the Ad Library has for it, and no ad is read. A quick way to compare brands or countries before a full run.

Tick Market statistics per search (includeMarketStats): at the end of the run, each search with at least 10 ads delivered gets ONE summary in the run's key-value store, in the record MARKET_STATS (Output tab; not in the dataset). Each summary holds the number of ads and how many are still active, the number of advertisers and the 10 biggest with their share, the ads by platform and by format, the days the ads ran (smallest, median, 75th percentile, largest), the grouped ads, the top landing domains, buttons and countries, the ads by start month, the spend and impressions Meta publishes (by currency) and the total the Ad Library shows for the search. It is worked out from the ads of that run, so use Max ads and the filters to choose what it covers.

AI image text

Tick AI image text (imageText): the text written in the ad images (an offer, dates, a brand name, a button) is read by an AI that runs inside the Actor, and written in imageText (the main image) and imageTexts (every image of the ad: the main image, the other images, the carousel cards, then the video preview; 10 at most). An image in which no readable text is found gives null and is not charged. Only Latin-script text is read (English, French, German, Spanish, Italian, Portuguese…). The option needs 2 GB of memory (Run options): with less, it is skipped, the ads are delivered as usual and nothing is charged for it. A very large image is skipped.

AI speech in videos

Tick AI speech in videos (videoTranscript): what is said in the ad's main video (the one in videoUrl) is written down by an AI that runs inside the Actor, into videoTranscript, with the language it hears in videoLanguage; the length of that video in seconds is written in videoDuration (also when it has no speech). The first 60 seconds of sound are read: that is where an ad says its hook, its offer and its call to action. A video with music only, no sound, or too few words gives null and is not charged; an ad without video costs nothing more. The option needs 2 GB of memory (Run options): with less, it is skipped, the ads are delivered as usual and nothing is charged for it. A very large video file is skipped.

AI labels

Fill AI labels (aiLabelNames) with your own labels, in English (discount, free shipping, testimonial…; up to 20), and an AI that runs inside the Actor judges the text of each ad against each of them. aiLabels holds one entry per label: label, score (from 0 to 1) and match (true when the label applies). Write name: what it means (for example competitor: mentions a competing product) to say more than the name alone. The text judged is the ad's body, title, caption, link description and cards, plus the text read in its images when AI image text is ticked too. Only ads written in English receive labels: an ad in another language, or without text, gets aiLabels: null and is not charged. The option needs 2 GB of memory (Run options): with less, it is skipped, the ads are delivered as usual and nothing is charged for it.

Ad score

Tick Ad score (includeAdScore) to sort the ads that look like winners first. Each ad gets adScore, from 0 to 100, and adScoreFactors, the points of each factor:

FactorPoints
longevity: days running90 days or more 40 · 60+ 34 · 30+ 28 · 14+ 20 · 7+ 12 · 3+ 6 · less 0
versions: identical ads grouped with it20 or more 25 · 10+ 20 · 5+ 15 · 2+ 8 · alone 0
platforms: Facebook, Instagram, Messenger, Audience Network, Threads5 per platform beyond the first, up to 15
countries: countries reached or targeted5 or more 10 · 2+ 5 · one 0
active: still running10

Advertisers keep paying for the ads that sell: an ad that has run for months, in many versions and on several platforms is a strong sign. The score is computed on the ad's own data, with no extra request, so it is fast. An ad without a start date has no score (null) and is not charged.

🔌 Integrations and API

Call the Actor via the Apify API, the JavaScript or Python clients, or connect it with integrations and webhooks (Make, Zapier, n8n, Google Sheets, Slack, Airtable…). The dataset can be fetched as JSON or CSV from any tool.

🤖 Use with AI agents (MCP)

AI agents (Claude, ChatGPT, Cursor…) can find and run this Actor through the Apify MCP server, billed to their Apify account like any run. It returns one item per ad of the Meta Ad Library (Facebook, Instagram, Messenger, Threads). Actor id: nice_dev/facebook-ads-library-scraper; MCP server with this Actor only: https://mcp.apify.com/?tools=fetch-actor-details,nice_dev/facebook-ads-library-scraper.

Smallest input, for a cheap first call:

{
"query": "running shoes",
"country": "US",
"maxItems": 10
}

Key output fields: url, pageName, bodyText, title, linkUrl, startDate, daysRunning, publisherPlatforms, imageUrl and videoUrl.

Cost: pay per ad saved plus a small fee per run start, options only when ticked; see the pricing section above. Cap each call with maxItems and, through the API, with the run option maxTotalChargeUsd.

❓ FAQ

The Meta Ad Library is published by Meta for ad transparency, and the Actor only reads what it shows publicly to any visitor, without a Facebook account. It logs in to nothing. Results can contain personal data (an advertiser who is a person, a "Paid for by" name, a page owner's address or phone with Page transparency, e-mails and phone numbers with the landing page contacts option), which is protected by GDPR and similar laws: do not store it without a legitimate reason. You are responsible for using the data in compliance with Meta's Terms of Use and applicable law. This Actor is not affiliated with Meta Platforms or Facebook.

Does it need a login or a proxy?

No Facebook account, no login, no cookies. Keep Apify Proxy (the default): the Actor picks the connection each page needs, and it is included in the price. With your own proxy URLs (proxyUrls), every request goes through them: Meta shows more than the first 30 ads of a search only to home connections. On the free Apify plan, without your own proxy URLs, you get the first 30 ads of each search (the run ends successfully and says so in its status); the residential connection beyond them is reserved for paid plans. A request Meta turns away ("Rate limit exceeded") is retried at once on a new proxy session, up to 10 times on top of the retries (without a proxy, after a pause of 5 seconds, doubled at each retry up to 150 seconds), and the search goes on from where it stopped.

Is the data safe to open in Excel or to show on a web page?

Ad texts, titles and captions are the advertisers' own words, copied as they are (catalog ads keep Meta's placeholders such as {{product.name}}). A text can begin with -, +, = or @ (a phone number, a title such as -30% today): Excel and Google Sheets may read such a cell of a CSV file as a formula or as a number. The Actor leaves the text as it is, so that the JSON and the API give the real value: when you open a CSV, import these columns as text. On a web page, escape every field like any text written by a stranger.

Known limitations

  • Spend, impressions and estimated audience are published by Meta for political and issue ads only, as ranges ($600K - $700K): spend keeps Meta's text, spendLower / spendUpper its bounds. For other ads they are null.
  • Commercial ads are listed by Meta only where the law requires it (EU, UK, Brazil…) or while they run: a stopped commercial ad shown only in the US is not in the Ad Library.
  • Meta's image and video links expire after a few days: use Save images and videos to keep the files.
  • totalCount is Meta's own count for the search, before the Actor's filters.
  • One search reads at most 10,020 ads (the first 30, then 999 pages of 10). When Meta has more, the run says so in its log, with the total Meta announced: narrow the search (country, dates, advertiser) or run several searches to read the rest.
  • Advertisers by name reads the best match of the Ad Library's advertiser search: check pageName and pageId, or use Advertisers with the page link or ID when names are close.
  • onlyNew remembers ad IDs, not their content: an ad whose text or end date changed is not returned again.
  • Two runs sharing the same stateKey at the same time may both return the same new ad.

A run that reaches its timeout stops itself about 45 seconds before it: no new page is asked, what it read is saved and, with onlyNew, remembered, and the run ends Succeeded with "Stopped before the run's timeout". Resurrect it to go on from there, or give the next run a longer timeout (Run options).

A run the platform stops without warning (out of memory)

  • Resurrect it: it goes on from where it stood at most a minute before the stop. What it had read since is read again, and the ads already saved are skipped: none is delivered or charged twice, and maxItems still counts them.
  • With onlyNew, the memory is saved after each write (at most once every 2 seconds): resurrect the stopped run and the ads it had saved meanwhile join the memory; leave it stopped for good, and the next run may return the ads of its last 2 seconds once more.

Something doesn't work?

The last line of the log counts the ads saved and filtered out, and the requests that failed after every retry. Those requests are listed, with the reason, in the FAILED_REQUESTS record of the run's key-value store. A run that saved nothing and had failed requests fails, and its last message gives the cause.

If Meta changes the Ad Library, you are told instead of paying for blank rows. If the first 20 ads read all lack their advertiser, start date, status or platforms, the run saves nothing more, stops and fails, and its last message names the missing field: at most those first ads are charged. An ad that postedAfter / postedBefore drops because it has no date at all counts among those 20. A run of fewer ads (a scheduled onlyNew run that finds a few new ones, a small Max ads) is checked at its end, from 5 ads: its ads are already saved, and the run fails with the missing field instead of ending green.

🛟 Support

Open an issue in the Issues tab with a link to your run: the run log and the FAILED_REQUESTS record of the key-value store show exactly which requests failed and why.