Facebook Ads Library E-commerce Ad Intelligence

Tracks what a brand or a specific advertiser Page is running on Meta's public Ad Library and returns one clean record per ad: the creative image or video, the copy, the call-to-action, which platforms it runs on, and how long it's been active. Built for e-commerce and DTC teams who want a competitor ad-spy feed instead of a raw Ad Library export - no Facebook login required, since the Ad Library is a public transparency tool.

It drives a real headless browser to Meta's public search UI (the same page you'd use at facebook.com/ads/library), reads the ad data straight out of the page's own data (not screen-scraped text), and stops once it has enough ads or the run's budget cap is reached.

Input

Field	Type	Default	Notes
searchTerms	array of strings	["Nike"]	Brand or product keywords, exactly as typed into the Ad Library search box. Matches ad copy and advertiser names - e.g. "Nike" also returns resellers' ads that mention Nike products.
pageIds	array of strings	[]	Numeric Facebook Page IDs. Use this to pull every ad from a specific advertiser instead of a keyword match. Find a Page ID via the "View all Page ads" link in the Ad Library or a Page's About panel. At least one of searchTerms or pageIds must resolve to something - the default searchTerms covers a first run.
countryCode	string	"US"	Two-letter country the ads targeted (not your own location).
activeStatus	enum	"active"	active, inactive, or all. Most competitor tracking wants active-only.
maxAdsPerSearch	integer	20	Stop once this many ads are found per search term / Page ID. 1-500.
proxyConfiguration	object	{ "useApifyProxy": false }	Off by default so the actor is free to try. See Known limitations - turn this on with the Residential group if runs start failing.

Output

One dataset record per ad creative. Example:

{
    "adArchiveId": "1249043200627555",
    "adLibraryUrl": "https://www.facebook.com/ads/library/?id=1249043200627555",
    "pageId": "15087023444",
    "pageName": "Nike",
    "pageProfileUrl": "https://www.facebook.com/nike/",
    "isActive": true,
    "startDate": "2026-03-17T07:00:00.000Z",
    "endDate": "2026-08-12T07:00:00.000Z",
    "publisherPlatforms": "FACEBOOK, INSTAGRAM, AUDIENCE_NETWORK, MESSENGER",
    "ctaText": "Shop now",
    "ctaType": "SHOP_NOW",
    "title": "Nike: Shoes, Apparel & Stories",
    "bodyText": "Celebra tu cumpleaños con Nike y obtén acceso a productos exclusivos, MSI, envío y devoluciones gratis el resto del año.",
    "linkUrl": "http://play.google.com/store/apps/details?id=com.nike.omega",
    "displayFormat": "DPA",
    "imageUrl": "https://scontent.xx.fbcdn.net/...",
    "videoUrl": null,
    "searchTerm": "Nike",
    "countryCode": "US",
    "scrapedAt": "2026-08-13T07:34:16.997Z"
}

imageUrl/videoUrl are direct CDN links from Meta and expire after a while, so download anything you need to keep. Meta does not expose exact spend or impression numbers for ordinary commercial ads through this surface (see limitations) - publisherPlatforms, run dates, and creative content are the reliable signals here.

Cost

Billed per ad record delivered (ad-scraped, $0.01) - see MONETIZATION.md for the full breakdown. A default run of 20 ads costs about $0.20. Set ACTOR_MAX_TOTAL_CHARGE_USD on the run to cap total spend; the actor checks the budget before every charge and stops cleanly, so you never pay for more than you asked for.

Known limitations

• No exact spend or impression numbers. Meta's public Ad Library only discloses spend ranges and reach estimates for political/social-issue ads. For ordinary commercial ads (the vast majority of e-commerce advertising) those fields are empty by design on Meta's side, not omitted by this actor.
• Catalog ads show template placeholders. Dynamic Product Ads and DCO creatives (common for retailers) often carry literal text like {{product.name}} in the underlying data because the real product feed is resolved per-viewer by Meta at render time. That's what Meta serves, not a parsing bug.
• Meta rate-limits and occasionally blocks non-browser traffic. This actor drives a real browser and works from a plain data-center IP in testing, but Meta's edge protection changes without notice. If a run starts failing with no ads collected, enable proxyConfiguration with the Residential group and retry.
• Keyword search matches ad copy, not just the brand's own ads. Searching "Nike" also surfaces resellers and affiliates whose ad copy mentions Nike. Use pageIds if you need ads from one advertiser only.
• Internal Meta data shapes change. The Ad Library's internal data layout isn't a stable public API and has changed before; a broken run after a Meta update, not stale ad data, is the most likely failure mode long-term.
• CDN media links expire. Save any images/video you need - Meta's URLs are signed and time-limited.

Legal

This Actor is an independent, third-party tool. It is not affiliated with, endorsed by, or sponsored by Meta Platforms, Inc.

It retrieves data by automating the public Ad Library web page, not Meta's official Graph API - the API's /ads_archive endpoint only serves political/social-issue ads to normal callers and does not cover ordinary commercial ads (see "How it works" in the source, or BRIEF.json). Meta's Terms of Service prohibit automated data collection from its products without prior permission, and Meta has pursued legal action against scrapers in the past. Using this Actor may not comply with Meta's terms. You are responsible for reviewing Meta's terms and applicable law before using this Actor, and for how you use the data it returns.