What the Meta Ad Library API actually returns

Engineers arrive at the Meta Ad Library API expecting a programmatic version of the web library. It is not that. The web library shows commercial ads; the API, outside the EU, returns political and social-issue ads only. Most projects discover this after the access request, which is the expensive order to discover it in.

What you have to do before the first request

1. Confirm your identity with Meta and be authorised for the Ad Library API. This is an identity check on a person, not a click-through developer signup.
2. Create an app and get an access token.
3. Query ads_archive on the Graph API with a search term or page ID, a country list, and the fields you want.

The fields are genuinely rich for what they cover: creative body and titles, the start and stop dates, the publisher platforms, spend and impressions as ranges, demographic and regional distribution, and the disclaimer string of whoever paid. For political research this is the system of record and nothing else comes close. The price is zero and the provenance is perfect.

The gap, stated plainly

If the ads you need are commercial, and you are not restricted to EU delivery, the API does not have them. No scope, no tier and no partnership changes that, because it is a product boundary rather than a rate limit.

The European picture is different. The Digital Services Act obliges very large platforms to publish an ad repository covering all ads, not only political ones, with published reach per ad. That is why EU-scoped ad data is richer than US-scoped ad data across every platform, and why a tool's coverage claims should always be read with a map in hand.

A practical consequence for anyone building on this: an EU-only pipeline can be honest and complete, and a global pipeline built from the same endpoint cannot. Say which one you have. Coverage that varies by country is the single most common silent error in ad intelligence, ours included, which is why AdLemur stores the source and geography of every observation rather than merging them into one number.

The options, with their real costs

• Official API, political scope. Free, perfectly sourced, and only answers political questions outside the EU. If that is your use case, stop here; you are done.
• The public library's own browser contract. The web library is public, and a collector can follow it the way a browser does. This is how most commercial coverage actually exists. It needs maintaining, because the contract is not a published API and changes without notice, and it needs a real stance on the platform's terms rather than a shrug.
• A commercial ad intelligence API. Someone else maintains the collectors and sells the result, typically a few hundred euros a month at the tier where API access is switched on. You are buying maintenance and normalisation, and inheriting their coverage gaps, which are rarely published.
• Generic scraping platforms. Cheap per run, and you own every breakage, every retry and every legal question. Fine for a one-off, poor as a dependency.

What to check before you trust any of them

Coverage claims in this category are mostly unfalsifiable as written. Four questions make them concrete:

1. Which countries, per platform? Not which platforms. A tool covering eight networks in the EEA and one globally will describe itself as covering eight networks.
2. How do you know a collection was complete? If a run stops early, absent ads look stopped. A source that cannot distinguish an exhausted run from a truncated one cannot report a stop date, and a stop date is what everything else is built on.
3. Where does the spend number come from? If it is not the political spend range or an EU reach figure, it is a model. That can be fine. It should be labelled.
4. What happens when the portal changes? Ask when their Meta adapter last broke and how long it took to notice.

How AdLemur handles it

AdLemur reads each platform's own public transparency surface and records what it saw, when, from which source, and whether the run reached exhaustion or a disclosed cap. Only a complete comparable collection can mark an ad stopped; a partial run stores a resumable cursor and says it is partial. Ads carry the EU, UK and Brazil reach values as separate figures because they measure different regions. LinkedIn collection is switched off rather than approximated, because there is no public contract we can validate.

The same records are readable by an agent over MCP, which is the part no library or spy tool offers: search_ads, list_ad_changes and get_ad return the evidence with its provenance attached, so a model reasoning over it can tell a measurement from a model. That surface is described in AdLemur MCP.

Is the Meta Ad Library API free?

Yes. Access requires identity confirmation and an authorised app, but there is no fee.

Can the Ad Library API return commercial ads?

Outside the EU, no. It returns political and social-issue ads. EU ad repositories are broader because the Digital Services Act requires them to be.

What is in ads_archive for the ads it does cover?

Creative text, start and stop dates, publisher platforms, spend and impression ranges, demographic and regional distribution, and the paying disclaimer. Ranges rather than exact figures.

How do people get commercial Meta ad data then?

By collecting the public library the way a browser does, or by buying a commercial ad intelligence API that does the same thing and maintains it. Both approaches inherit the library's own limit: an ad that has stopped is no longer there to collect.