Meta's Ad Library API is not for competitor research

Yes, Meta has an official Ad Library API, and it returns two kinds of ads only: ads about social issues, elections or politics delivered anywhere in the past seven years (except that queries for EU countries were retired on October 6, 2025), and ads of any type delivered to the UK or EU in the past year. To use it you confirm your identity at Facebook.com/ID, which can take a few days, then create a Meta developer app. 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 Meta's API landing page says as much in one sentence:

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. In the landing page's words:

• "Ads about social issues, election or politics that were delivered anywhere in the world during the past 7 years"
• "Ads of any type that were delivered to the United Kingdom (UK) or European Union during the past year"

That second bucket is the one people miss. It is the only place ordinary commercial ads appear in the API at all, and only for UK or EU delivery.

So a US-only advertiser selling a US-only product has no API coverage at all.

The ad_type parameter can also narrow results to Meta's special ad categories (HOUSING_ADS, EMPLOYMENT_ADS and FINANCIAL_PRODUCTS_AND_SERVICES_ADS, which "now replaces CREDIT_ADS") as well as POLITICAL_AND_ISSUE_ADS. Those are filters inside the two buckets above. Meta's coverage statement doesn't change for them, and nothing on the page says a US housing or job ad becomes retrievable.

The UK rule has a start date

The Ad Library's landing page words the UK bucket differently from the API page. It promises:

Ads that have run anywhere in the EU in the past year

Ads that have run in the UK in the past year and that have run after July 1, 2025

The API page has no July 2025 condition. In October 2026 the two readings return the same thing, because a "past year" window already starts after July 2025. The date matters if you're working from data or write-ups pulled in late 2025, when the UK archive was shorter than a year. The API's release notes list a new field on the same date, July 1, 2025: total_reach_by_location, whose supported locations are "EU, BR, and UK".

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.

There are four retention rules, which the Ad Library landing page and its FAQ lay out:

So filtering to "Inactive" on a US search doesn't unlock ad history. It narrows your results to ads that were also shown in the UK or EU, and only their last twelve months. That can include a US-only brand: an ad doesn't have to be targeted at Europe to count. Open an inactive ad's "Transparency by location" panel and it can say the advertiser "did not target an audience in the EU" while still listing the ad's EU reach. For an ordinary ad that reached nobody in the UK or EU, Meta's pages describe no archive at all.

Any advice built on "look at your competitor's dead ads to see what they stopped running" only works for the ads that reached the UK or EU. For a US brand, that is a slice of what it stopped running, not the whole of it.

What data does the API return per ad?

The API page says "All available ads will have" a Library ID, the creative content, the Page name and ID, the delivery dates, and where the ad appeared. In the field table that means the creative bodies, link titles, captions and descriptions, creation time, delivery start and stop times, a snapshot URL, publisher platforms and languages.

That is useful for creative research. Missing: impressions, spend, reach, demographics and targeting.

Those fields exist, but the same page gates each one:

• 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, and political ads delivered to Brazil: age_country_gender_reach_breakdown, target_ages, target_gender, target_locations
• Political ads delivered to Brazil: br_total_reach

The page contradicts itself on one of these. Its summary says ads delivered to the UK and EU "will also have: Total impressions an ad received in the UK and EU (estimated)", while its field table says impressions is "Available only for POLITICAL_AND_ISSUE_ADS". No field in the table carries a UK or EU impression count, so plan on the table.

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, "as specified in currency". Nobody can compute a CPM from this.

Two more details from the page save you a support ticket. Start dates are first-impression dates "As of August 2020"; before that they were "based on the dates the advertiser provided". And error 1357045 "is usually associated with an ad blocker".

Before building anything on it, know this: for an ordinary commercial ad that reached nobody in the UK or EU, no performance data exists in public. Ads delivered there get reach and age, gender and country breakdowns, but the spend and impressions fields stay political-only. Any tool or thread presenting competitor spend or impressions for a normal brand is estimating, and should say so.

Can you bulk-download ads from the Ad Library?

No. The ad_snapshot_url field description is direct about it:

While you cannot currently download a batch of archived ads, you can download ad creative such as images and text for an individual ad. If you do so, it must be for analysis and you must comply with the data storage terms in our Terms of Service.

Meta's alternatives to the API cover more of what is running now, not more history. The Ad Library website shows every ad currently running, including the commercial ads the API leaves out, but offers no bulk download, and stopped commercial ads stay visible only if they reached the UK or EU. The Ad Library Report gives "overall spending totals", but only "For ads about social issues, elections or politics". Meta publishes no spend or impression figure for an ordinary commercial ad in the Ad Library or its API, so when a third-party tool shows one for a normal brand, it is that tool's estimate.

How do you get access to the Ad Library API?

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

The API page lists the steps. Go to Facebook.com/ID "and follow the confirmation process required to run ads about social issues, elections or politics. It can take a few days to confirm the information you submit." Then create a Meta for Developers account, agree to the Platform Policy, and create an app; you'll need a user access token. There's also a permission check: "Users need to have a role or be assigned a role by the app owner to make queries." The page says the API is available in "over 100 countries".

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. Each results page holds 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, "Calls to this api have exceeded the rate limit". Meta documents the error but publishes no calls-per-hour figure, so you'll have to discover your own ceiling.

The active-status default and a stale country note

ad_active_status has two documented defaults. The parameter table says it "Defaults to ACTIVE". A release note dated June 30, 2021 says "We changed ad_active_status's default value to ALL (previously ACTIVE)". 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 did not reach any location in the EU will only return if they are about social issues, elections or politics". That omits the UK coverage that the same site's API landing page describes. Trust the landing page.

EU political ads are gone from the API

Meta ended political, electoral and social-issue advertising in the EU on 6 October 2025, citing the EU's Transparency and Targeting of Political Advertising (TTPA) regulation. The API release notes retired the matching query on the same date: pairing ad_type POLITICAL_AND_ISSUE_ADS with ad_reached_countries "for any countries in the European Union will no longer be available." The web UI matches: pick Germany or Slovenia as the country and the "Issues, elections or politics" category isn't in the list, where it is for the US and the UK.

Meta's pages don't say whether historical pre-October-2025 EU political ads remain retrievable anywhere. If your work depends on that, verify it directly.

When to use the API, and when to use the website

1. Political ads or UK/EU ads → the API works well. Seven years, worldwide except the EU since October 6, 2025, with spend and demographic ranges for political ads.

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 outside the UK and EU. It doesn't exist publicly. UK and EU delivery adds reach, never a spend or impressions field.

4. Set ad_active_status explicitly. The docs contradict themselves.

5. Budget for identity confirmation before you plan around API access.

6. Treat "inactive" results as a UK/EU sample, not as history. The UK and EU both cover the past year. The UK's July 1, 2025 floor no longer matters now that a year back lands after it.

7. Use the Ad Library website to see what creative is running right now and what a competitor keeps paying to keep live. That work is reading ads, not querying them.

Sources

• Meta Ad Library API — Meta (accessed October 18, 2026)
• Graph API Reference: Ads Archive — Meta for Developers (accessed October 18, 2026)
• Ad Library API release notes — Meta (accessed October 18, 2026)
• Meta Ad Library — Meta (accessed October 18, 2026)
• Ending Political, Electoral and Social Issue Advertising in the EU in Response to Incoming European Regulation (accessed October 18, 2026)

---

Meta revises these pages without notice, so 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.