The short answer
The Meta Ad Library API (the ads_archive endpoint) returns political and issue ads worldwide, plus commercial ads only if they delivered in the EU. You need a confirmed identity and a developer app. It gives text, start dates and EU reach, but no spend for commercial ads and no video transcripts.
What the API covers, in one table
The Meta Ad Library API is the programmatic side of the public Ad Library. It is one Graph API endpoint, ads_archive, that returns archived ad objects. It sounds like the answer to every competitor research problem. For US commercial research it mostly isn't, and the reason is coverage.
| Ad type | Returned by the API? | Spend and impressions | Reach and targeting |
|---|---|---|---|
| Political, election and social issue ads, any country | Yes | Yes, as ranges | Demographic distribution, region |
| Commercial ads that delivered in the EU | Yes | No | EU reach, by country, age and gender; targeting settings |
| Commercial ads that never delivered in the EU | No | No | No |
Meta's ads_archive reference says it plainly: ads that did not reach any location in the EU will only return if they are about social issues, elections or politics. A DTC brand that sells only in the US is invisible to the API, even though its ads appear in the web library.
How to get access
Meta's Ad Library API page lists three steps:
- Confirm your identity and location. Go to facebook.com/ID and complete the same confirmation required to run ads about social issues, elections or politics. It can take a few days.
- Create a Meta for Developers account and accept the Platform Policy.
- Create an app from the Ad Library API page ("Access the API"), then generate an access token for it.
Once that is done you call https://graph.facebook.com/<version>/ads_archive with your token. Calls are rate limited, and the API returns an error when you exceed the limit, so paginate politely.
The parameters that matter
From the ads_archive reference:
| Parameter | What it does |
|---|---|
ad_reached_countries | Required. ISO country codes, or ALL |
search_terms | Keywords, 100 characters max |
search_type | KEYWORD_UNORDERED or KEYWORD_EXACT_PHRASE |
search_page_ids | Up to 10 Page IDs |
ad_active_status | ACTIVE, INACTIVE or ALL |
ad_delivery_date_min / _max | Ads delivered after or before a date |
ad_type | ALL, POLITICAL_AND_ISSUE_ADS, EMPLOYMENT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS, HOUSING_ADS |
media_type | IMAGE, MEME, VIDEO, NONE or ALL |
publisher_platforms | Filter by Meta app |
languages | Languages contained in the ad |
A minimal request for a brand's active ads delivered in Germany looks like this:
GET /<version>/ads_archive
?search_page_ids=<PAGE_ID>
&ad_reached_countries=["DE"]
&ad_active_status=ACTIVE
&fields=id,page_name,ad_delivery_start_time,ad_creative_bodies,ad_creative_link_titles,ad_snapshot_url,eu_total_reach
&access_token=<TOKEN>The fields you get back
The archived ad reference lists the fields. Grouped by who gets them:
Every ad the API returns: id, page_id, page_name, ad_creation_time, ad_delivery_start_time, ad_delivery_stop_time, ad_creative_bodies, ad_creative_link_titles, ad_creative_link_descriptions, ad_creative_link_captions, ad_snapshot_url, languages, publisher_platforms.
EU and UK ads: eu_total_reach, beneficiary_payers, age_country_gender_reach_breakdown, target_ages, target_gender, target_locations.
Political and issue ads only: spend, impressions, currency, bylines, demographic_distribution, delivery_by_region, estimated_audience_size.
Two fields deserve a note. ad_creative_bodies and ad_creative_link_titles are arrays: an ad with several text versions returns several entries, which is how you count variants programmatically. And ad_delivery_start_time gives you days live. Those are two of the four signals we use to find winners, described in how to find winning Facebook ads.
What the API can't give you
| Research need | API answer |
|---|---|
| Days live | Yes, from ad_delivery_start_time |
| Variant count | Partly, from the text arrays (image and video changes are not listed) |
| Spend for commercial ads | No. See estimating competitor ad spend |
| US-only commercial ads | No |
| Video media file | No, only a snapshot URL |
| What the video says | No |
| Landing page content | No, only link captions and titles |
The transcript gap is the expensive one. On the Ad Radar board of 2,443 winning Meta ads, 1,968 are video (81%). Of the 1,682 videos with a transcript, 1,679 open with a spoken line that never appears in their written text. The API returns the written text. The hook is in the audio.
What the?
- Est. spend
- $4.9M
- Days live
- 57
- Format
- Video, 76s
- Variants
- 3
The spoken opener is a two-word pun on the product name. The API would return the body copy about coverage and finish, and miss the joke that starts the ad.
Image ads fare better, because their message lives in the fields the API returns:
The New Hume Band Is Finally Here
- Est. spend
- $415K
- Days live
- 136
- Format
- Image
- Variants
- 12
Twelve versions of a launch headline from a Page that is not the brand's own. For an image ad like this, the text arrays capture most of what matters, provided the ad also delivered in the EU.
API vs the web library
People often assume the API is the web library with a download button. It is narrower.
| Web library | API | |
|---|---|---|
| US-only commercial ads | Visible while active | Not returned |
| EU commercial ads | Visible, inactive kept one year | Returned, same retention |
| Political and issue ads | Visible, kept seven years | Returned, with spend ranges |
| Login needed | No | Confirmed identity, developer app, token |
| Video playback | Yes | Snapshot URL only |
| Bulk export | No | Yes, paginated |
So the web library sees more ads and the API sees them more efficiently. For a US brand the web library is the only first-party view of its competitors. The step-by-step for that is in how to use the Meta Ad Library.
When the API is the right tool
- Political and issue ad research. This is what it was built for, with spend ranges and demographics.
- EU market research. If your competitors sell in Europe, you get start dates, text, reach and targeting, including inactive ads.
- Monitoring at scale for brands that also run in the EU. Pull text and start dates weekly and diff them.
- Academic and journalistic work, where coverage of political ads matters more than commercial creative.
When it isn't
- US-only DTC brands. The API returns nothing for their commercial ads.
- Hook research on video. You need transcripts, which means rendering and transcribing every ad yourself.
- Spend ranking. You need an estimate either way.
For US commercial research, most teams end up with the web library plus a tool that tracks ads over time, keeps transcripts and estimates spend. Ad Radar does that for Meta ads with $50k+ in estimated spend and exposes it through an MCP server, so you can query winning ads from Claude without writing API code. Our pieces on Claude MCP for ad research and Meta Ad Library alternatives cover the options.
A sensible build if you do use the API
- Store raw responses, keyed by
id. Ads disappear from the EU archive one year after their last impression. - Recompute days live and text-version counts on every pull and keep the history, so you see changes, not snapshots.
- Render
ad_snapshot_urlonly for ads that pass a filter (for example, 30+ days live), then extract and transcribe video. Doing it for every ad is slow and wasteful. - Tag the transcripts with a fixed vocabulary. Our swipe file guide has one you can reuse.
Figures marked as estimated spend come from Ad Radar's model of engagement on public Meta Ad Library ads. They are estimates, labeled as such, and are best used to rank ads against each other.