Facebook Ads Library Scraper

The Actor reads public advertising data from the Meta Ad Library and returns it as structured records. It covers three related tasks: searching all advertisers by keyword, collecting every ad belonging to one advertiser Page, and resolving a brand name to the Page ID the other two modes require.

It serves as a Meta Ad Library API for cases the official Ad Library API does not cover. That interface returns ordinary commercial ads only when the audience is in an EU member state or the UK, where the Digital Services Act compels disclosure; a commercial ad targeting the United States alone returns nothing through it, despite being visible on the Ad Library website. It also requires a Meta developer account with identity verification. This Actor reads the same public data the website exposes, across all countries, and requires no Meta credentials.

Selecting a function

The scraperType field determines what a run does. It defaults to search.

Value	Label	Purpose	Required input
search	Search Ads	Find ads across all advertisers matching a query	q, or a Start URL
page	Browse page ads	Collect every ad from one advertiser Page	page_id
searchPages	Find advertiser page	Resolve a brand name to its Page ID	q

The three modes form a sequence. A brand name resolved through searchPages yields a pageId, which becomes the page_id for a page run.

Accepted input

Field	Type	Default	Description
scraperType	enum	search	Which of the three functions the run performs.
startUrl	string	—	A Meta Ad Library URL. Its query parameters populate any field left empty.
q	string	—	Search query in search mode; brand or company name in searchPages mode. Unused in page mode.
page_id	string	—	Numeric Page ID of the advertiser. Required in page mode.
country	string	US	ISO 3166-1 alpha-2 country code.
maxItems	integer	50	Maximum records saved. 0 removes the limit.
enrichAdDetails	boolean	false	Fetches the full detail record for every ad returned.
active_status	enum	all	all, active, inactive.
ad_type	enum	ALL	ALL, POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, EMPLOYMENT_ADS, CREDIT_ADS.
media_type	enum	all	all, image, video, meme.
search_type	enum	—	keyword_unordered or keyword_exact_phrase.
publisher_platforms	array	—	Restricts results to selected Meta platforms.
content_languages	string	—	Comma-separated ISO 639-1 codes.
date_min / date_max	string	—	Bounds on the ad's active period, YYYY-MM-DD.
page_ids	string	—	Comma-separated Page IDs restricting a search to specific advertisers.
is_targeted_country	boolean	false	Returns only ads specifically targeting country.
potential_reach_min / _max	integer	—	Bounds on estimated audience size.
sort_mode	enum	—	total_impressions. Leave empty for default ordering.
sort_direction	enum	—	desc.

{
  "scraperType": "search",
  "q": "running shoes",
  "country": "US",
  "maxItems": 50,
  "active_status": "active",
  "media_type": "video"
}

Filters accepted by each mode

Filters are not shared across all three modes. A filter set in a mode that does not accept it is ignored rather than rejected, so a run that appears to disregard a setting is usually a mode mismatch.

Filter	search	page	searchPages
country	yes	yes	yes
active_status, media_type, publisher_platforms, content_languages, date_min, date_max, sort_mode, sort_direction	yes	yes	no
ad_type	yes	no	yes
search_type, page_ids, is_targeted_country, potential_reach_min, potential_reach_max	yes	no	no

Response fields

Ad records, returned by search and page:

Field	Contents
ad_archive_id	Identifier of the ad within the Ad Library
page_id	Numeric ID of the advertiser's Page
page_name	Name of the advertiser's Page
is_active	Whether the ad is currently running
start_date	Unix timestamp at which the ad began running
end_date	Unix timestamp at which it stopped; 0 while still active
publisher_platform	Meta platforms the ad ran on
currency	Currency of the spend and reach figures
spend	Estimated spend range, where Meta publishes one
reach_estimate	Estimated audience reach, where Meta publishes one
categories	Ad categories reported by Meta
snapshot	Creative payload: body text, title, call to action, images, videos, link
details	Full detail record; present only when enrichAdDetails is enabled

Advertiser Page records, returned by searchPages:

Field	Contents
pageId	Page ID, used as page_id in page mode
name	Page name
category	Facebook category of the Page
likes	Number of likes on the Page
verification	Verification status
instagramUsername	Linked Instagram username, where one exists

{
  "ad_archive_id": "1234567890123456",
  "page_id": "20531316728",
  "page_name": "Example Brand",
  "is_active": true,
  "start_date": 1751328000,
  "end_date": 0,
  "publisher_platform": ["FACEBOOK", "INSTAGRAM"],
  "currency": "USD"
}

Behaviour of the Start URL

A Meta Ad Library URL supplied as startUrl is parsed into input fields, and its values fill only those fields left empty. A field set explicitly always takes precedence over the same parameter in the URL. The URL itself is not forwarded upstream.

Two normalisations are applied because the Ad Library interface exposes options the upstream endpoint does not. Sort metrics other than total_impressions are dropped, and ascending sort is converted to descending. The URL therefore continues to drive the run rather than failing validation.

A URL of the "browse this Page's ads" form — one carrying view_all_page_id, or search_type=page — contains no keyword. Such a URL reroutes the run to page mode automatically and supplies page_id from the URL, irrespective of the selected scraperType.

Behaviour on partial results

Ads are retrieved through a cursor in pages of 20. Collection ends when the upstream returns no cursor, reports no further pages, or returns an empty page.

A request that fails mid-run does not abort the run or discard what preceded it. The failure is logged, records already collected are retained, and the run finishes normally. A dataset smaller than maxItems therefore indicates either that the result set was exhausted or that a page failed, and the run log distinguishes the two.

Enrichment is applied per ad and requires both ad_archive_id and page_id to be present on the record. An enrichment request that fails leaves that record without a details field, does not interrupt the run, and is not charged. Each successful enrichment issues one additional request and one additional billed event, so a 500-ad run with enrichment enabled performs 500 extra requests.

Frequently asked questions

Is the Meta Ad Library API free? Meta's official Ad Library API costs nothing, but access requires a Meta account, government-ID identity verification, and an approved developer app, and its coverage is narrower than the Ad Library website. Ads about social issues, elections, and politics are fully covered. Ordinary commercial ads are returned only where the audience is in the EU or UK, carry a single eu_total_reach figure with no spend or impression data, and are absent entirely for audiences outside Europe. This Actor is paid, needs no Meta account or access token, and is not subject to those restrictions.

What is the Meta Ad Library? A public archive Meta maintains of advertising running across Facebook, Instagram, and its other platforms. Ads about social issues, elections, and politics are retained for seven years and carry spend and reach disclosure. Ordinary commercial ads are visible while running and for roughly a year after delivery ends, after which the record is gone — so historical commercial analysis depends on capturing snapshots as ads run rather than querying the archive later.

Where is the Meta Ad Library found? At facebook.com/ads/library. A search performed there produces a URL that can be pasted into startUrl, which reproduces the same filters without setting them by hand.

Why does a filter appear to have no effect? Most commonly because the selected mode does not accept it; see the filter table above. ad_type, for instance, applies in search and searchPages but not in page. Unaccepted filters are ignored silently rather than raising an error.

Why are spend and reach_estimate empty on most records? Meta publishes those figures only for ads in regulated categories. For ordinary commercial ads they are absent upstream and are returned empty rather than estimated.

What causes a run to return fewer records than maxItems? Either the result set was exhausted, or a page request failed and the run ended early while retaining what it had collected. The run log records which occurred. Narrow filters — a short date range combined with is_targeted_country, for example — commonly exhaust a result set well below the limit.

How is a Page ID obtained? Through searchPages, which takes a brand name in q and returns matching advertiser Pages with their pageId. That value is then supplied as page_id to a page run. A Meta Ad Library URL already containing view_all_page_id supplies it automatically.