TerradsTerrads
← All posts

Meta's Ad Library API is not for competitor research

There is an official API for the Meta Ad Library. It covers political ads and ads that ran in the UK or EU — and for anything else, Meta's own documentation tells you to go use the website.

ChrisUpdated September 15, 20267 min read

The Meta Ad Library API returns two kinds of ads: ads about social issues, elections or politics delivered anywhere in the past seven years, and ads of any type delivered to the UK or EU in the past year. A US-only advertiser has no API coverage at all, and no ordinary commercial ad comes with spend or impressions.

The reasonable assumption goes like this: the Meta Ad Library is a public database of ads, Meta ships an API for it, therefore you can pull a competitor's creative programmatically and get on with your analysis.

The first two clauses are true. The third doesn't follow, and the sources you'll find disagree with each other about why — some say the endpoint covers EU commercial ads broadly post-DSA, others say it's political ads only. Somebody is wrong.

Meta's API landing page settles it in one sentence, and it's worth quoting exactly:

To search for all ads currently running across Meta technologies, please use the Ad Library.

That is the documentation telling you the API is not the tool for the job.

What does the Meta Ad Library API cover?

Two things, and only two:

  • Ads about social issues, elections or politics delivered anywhere in the world in the past 7 years.
  • Ads of any type delivered to the United Kingdom or European Union in the past 1 year.

That second bucket is the one people miss, and it exists because of the EU's Digital Services Act plus a parallel UK transparency commitment — not because Meta decided to open up commercial ad data.

So: a US-only advertiser selling a US-only product has no API coverage at all. Not limited coverage. None.

The same limit bites in the web UI

This trips people up because the website looks like it has history. It has an Active-status filter with an "Inactive ads" option, so you flip it, and you get results.

Here's what's really happening. There are three retention regimes, which the Ad Library's own landing page lays out:

Ad typeWhat's retained
Commercial adsActive only — no history
Social issues, elections, politicsActive and inactive, 7 years
Anything delivered to the UK or EUArchived 1 year after its last impression

So filtering to "Inactive" on a US search doesn't unlock ad history. It quietly narrows your results to the advertisers who also ran in the UK or EU — and only their last twelve months. Search a purely domestic advertiser and the inactive filter returns nothing at all, which is the correct result and looks exactly like a bug.

Any advice built on "look at your competitor's dead ads to see what they stopped running" only works for advertisers with UK/EU delivery. For everyone else there are no dead ads to look at.

What you get per ad

For every ad the API returns: the Library ID, the creative bodies, link titles, captions and descriptions, creation time, delivery start and stop times, a snapshot URL, page ID and name, publisher platforms, and languages.

Genuinely useful for creative research. Notably absent: impressions, spend, reach, demographics, targeting — all of it.

Those fields exist, but they're gated:

  • Political / issue ads only: impressions, spend, currency, bylines, demographic_distribution, delivery_by_region, estimated_audience_size
  • Ads delivered to the EU: beneficiary_payers, eu_total_reach
  • Ads delivered to the UK & EU: age_country_gender_reach_breakdown, target_ages, target_gender, target_locations

And where you do get numbers, they're coarse buckets, not values. Impressions come back as ranges like 10K-50K or >1M; spend as $1K-5K. You cannot compute a CPM from this. Nobody can.

This is the single most important thing to internalise before building anything on it: for an ordinary commercial ad, no performance data exists in public. Any tool or thread presenting competitor spend or impressions for a normal brand is estimating, and should say so.

Getting access is a real hurdle

This isn't a "sign up for a key" API.

You need to confirm your identity and location — the same government-ID-backed process Meta requires of political advertisers, via Facebook.com/ID, which Meta warns can take days. Then a developer account, then an app, then an access token. There's also a permission check: a user needs a role on the app to make queries.

That's a proportionate amount of friction for a political-transparency dataset. It's a lot of friction to discover afterwards that your commercial ads aren't in it.

Once you're through, the endpoint is:

GET https://graph.facebook.com/<version>/ads_archive

ad_reached_countries is required. Results page at a maximum of 5,000 ads; search_terms is capped at 100 characters; search_page_ids takes up to ten IDs. Rate limiting exists and surfaces as error code 613 — Meta documents the error but publishes no calls-per-hour figure, so you'll have to discover your own ceiling.

Two contradictions in Meta's own docs

Worth knowing before they cost you an afternoon.

ad_active_status has two documented defaults. The parameter table says it defaults to ACTIVE. A release note says the default was changed to ALL. Both cannot be current. Always set it explicitly and don't rely on either.

The ad_reached_countries note is stale. It says ads that didn't reach the EU only return if they're political — which omits the UK coverage that the same site's API landing page describes. Trust the landing page.

One more thing that changed

Meta ended political, electoral and social-issue advertising in the EU on 6 October 2025, citing the EU's political-advertising regulation. The API release notes retired the corresponding query combination: you can no longer pair the political ad type with EU countries. The web UI matches — pick Germany as the country and the "Issues, elections or politics" category simply isn't in the list, where it is for the US.

What I could not establish is whether historical pre-October-2025 EU political ads remain retrievable anywhere. If your work depends on that, verify it directly rather than assuming either way.

The practical version

  1. Political ads or UK/EU ads → the API is genuinely good. Seven years, worldwide, with spend and demographic ranges.
  2. Commercial ads outside the UK/EU → the API has nothing. Use the website, as the documentation says.
  3. Never expect performance data for a normal brand's ads. It isn't withheld from you specifically; it doesn't exist publicly.
  4. Set ad_active_status explicitly. The docs contradict themselves.
  5. Budget for identity verification before you plan around API access.
  6. Treat "inactive" results as a UK/EU sample, not as history.

None of this makes the Ad Library less useful for the thing it's actually good at — seeing what creative is running right now, and what a competitor keeps paying to keep live. It just means that work is reading ads, not querying them, and the sooner you know that the less time you spend looking for an endpoint that was never going to answer your question.

Sources

Sourced from Meta's Ad Library API documentation, its release notes, the Graph API reference and the live Ad Library, all checked 10 September 2026; links re-verified 15 September 2026. Meta revises these without notice — confirm against the current docs before building on any of it.

Terrads has an ad library built in, for the research this API won't do: what's running now, grouped so you can actually read it.