Meta Ad Library API: Who Gets Access, What It Returns, and Why Commercial Ads Outside the EU Are Not in It

The API is the first thing a developer asks about after seeing the Ads Library. The honest answer for most readers of this site is: it will not give you what you want. Here is precisely what it gives.

1. Two kinds of ad, and only two

Meta's own description of the API, checked 2026-09-13, says it exists to analyze "ads about social issues, elections or politics, as well as ads that deliver to the EU and associated territories". Read that sentence twice. It is a list of two things:

Ad	In the API	Why
Social issues, elections or politics, any country	Yes, kept 7 years	Meta's political transparency commitment since 2018
Any ad that delivered in the EU (and the UK)	Yes, kept ~12 months after last impression	The EU Digital Services Act's ad-repository rule
Commercial ad that delivered only in Taiwan, the US, Southeast Asia, anywhere else	No	Nothing requires it, so Meta does not expose it
Branded content (creator partnership posts)	Yes for authorized users	Separate branded-content transparency

For an advertiser buying accounts to run ads in Taiwan or the US, row three is the whole story. A query for a Taiwanese retailer with ad_type=ALL returns an empty list, and no parameter changes that. The web version shows those ads; the API does not.

2. Getting access

Three steps, each a day or two:

1. Identity confirmation. Meta asks for a government ID and, in some countries, a mailed address code. This is the same confirmation used for political advertisers.
2. A developer app. Create an app at developers.facebook.com. It does not need review for the Ad Library API, but it needs to exist so you can mint a token.
3. An access token. A user token from the app; it expires, so anything scheduled needs a refresh step.

The identity step is where most people stall, and it is not skippable. When we set this up in 2026 for a client's EU campaign monitoring, the ID review took 3 days and the address code another 8; the app and token took 20 minutes. Budget two weeks before the first successful call.

3. The ads_archive endpoint

Everything goes through one Graph API endpoint:

GET https://graph.facebook.com/v21.0/ads_archive
  ?search_terms=<text>            (or search_page_ids=<id,id>)
  &ad_reached_countries=['TW']    (required, ISO-2 list)
  &ad_type=POLITICAL_AND_ISSUE_ADS  (or ALL, which only returns results for EU/UK countries)
  &ad_active_status=ACTIVE        (ACTIVE / INACTIVE / ALL)
  &fields=id,page_name,ad_creative_bodies,ad_delivery_start_time,ad_delivery_stop_time,publisher_platforms,ad_snapshot_url
  &access_token=<token>

Three things the documentation does not stress enough:

• ad_reached_countries is required and is the switch. With TW it returns only political ads; with an EU country it returns everything that delivered there. There is no "all countries" value that unlocks commercial ads globally.
• ad_snapshot_url is the only way to see the creative. The API returns text bodies and metadata, not the image or video. The snapshot URL renders the ad card, and it needs the token appended to open.
• Paging is by cursor, not offset. A large Page's ads come back a few dozen at a time with a next cursor; a script that assumes a page number will loop.

4. The EU-only fields

For ads that delivered in the EU, the DSA adds fields that do not exist anywhere else in the Meta ecosystem:

Field	What it holds
eu_total_reach	Total accounts reached in the EU
age_country_gender_reach_breakdown	Reach split by age band, country and gender
target_ages, target_gender, target_locations	The audience settings the advertiser chose
beneficiary_payers	Who benefits from and who paid for the ad

This is the closest thing to seeing a competitor's Ads Manager that exists, and it is why EU-market advertisers get more from the API than anyone else. For a Taiwanese advertiser it is a curiosity: the fields are there, they are empty for your market.

5. What to do instead

If your market is not the EU, the practical stack is:

1. The web version with filters saved as URLs. The search link builder turns the seven filters into a bookmarkable link. Open it weekly, read the start dates; the method is in section 5 of the Ads Library guide.
2. A paid tool for history. The library shows one year and no trend; tools that store the web data over time add "how long has this run" and "when did they change". Which one, and whether it is worth it, is in Ads Library vs spy tools.
3. Not a scraper you maintain yourself. They work until the page markup changes, and the library's markup changes several times a year. Every one we have seen an advertiser build in-house was abandoned within 6 months.

6. The same picture on other platforms

TikTok's Commercial Content Library and Google's Ads Transparency Center have API-like exports with the same EU-only shape; LinkedIn has none. The comparison is in every platform's ad library. The pattern is consistent: transparency by regulation covers the EU, transparency by choice covers political ads, and commercial ads elsewhere are web-only everywhere.

When the API turns out to be empty for your market, the useful work is elsewhere: a weekly swipe file from the web version, and the account layer that lets you run what you learn. The catalog has the 4 layers a first campaign needs; the first-run bundle has them assembled. Two weeks of API paperwork buys a token that returns 0 rows for a Taiwanese or US advertiser; 30 minutes a week in the web version buys the same competitor picture the API would, for the 1 market you actually run in.

---

Sources, checked 2026-09-13

• Ad Library API: facebook.com/ads/library/api
• Ad Library tools for researchers: Meta Transparency Center: transparency.meta.com
• ads_archive reference: Meta for Developers: developers.facebook.com
• The Digital Services Act: European Commission: digital-strategy.ec.europa.eu
• The identity-review timings in section 2 are from our own setup in 2026 and will vary by country.