Facebook Ad Library API: What It Can and Can't Return

Search for "Facebook Ad Library API" and you will find a lot of tutorials. Most skip the paragraph that matters: the official API does not return most commercial ads.

We spent a long time on this question because Seercraft is built on the public Ad Library. This post explains what the API returns, who it is for, how access works, and what to do if you need commercial ads from competitors.

Everything about the API below comes from Meta's own developer reference unless we say otherwise.

What is the Ad Library API?

It is a Graph API endpoint called ads_archive. You send a search, it returns ads from the Meta Ad Library as JSON. Meta says it returns archived ads based on keyword searches of text, images, audio from video and the call-to-action button.

A basic request looks like this, using Meta's own example for political ads in the US:

curl -G \
  -d "search_terms='california'" \
  -d "ad_type=POLITICAL_AND_ISSUE_ADS" \
  -d "ad_reached_countries=['US']" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<VERSION>/ads_archive"

Meta's own example is about political ads, and that tells you where the API's strength is.

What can the API return?

Three groups of ads, with very different amounts of detail.

1. Social issue, election and political ads

These are the ads with the most data. Meta keeps them in the library for 7 years, active or not. In the API they come with extra fields that only exist for this type of ad: spend, impressions (both as ranges), the estimated audience size, demographic distribution, regional delivery, the currency and the "paid for by" byline.

2. Ads delivered in the EU (and UK)

Because of the EU's Digital Services Act, ads that reached the EU come with transparency fields even when they are commercial. For EU delivery, the reference lists estimated total reach and reported beneficiaries and payers. For the UK and EU, it lists the targeting choices (ages, gender, locations included or excluded) and a reach breakdown by age, country and gender.

Meta's tools page says ads delivered in the EU and associated territories are archived for one year after their last impression.

3. Everything else

Here is the sentence from Meta's reference that matters most. For the ad_reached_countries parameter: "Ads that did not reach any location in the EU will only return if they are about social issues, elections or politics."

So a commercial ad that only ran in the US, India or Brazil is not returned by the API. A US skincare brand's ads to US customers are not in it. That rules out most of the competitor research a marketing team wants.

What you can still get for a commercial ad that reached the EU: the copy, the link text, the start and stop times, the Page, the platforms, the languages and a snapshot URL that shows the ad. You do not get spend, impressions or demographic data, because those fields exist only for political and issue ads.

What are the API's limits?

From the reference, here are the practical ones.

• A country is required. Every call needs ad_reached_countries, either ALL or one or more country codes.
• Search terms are capped at 100 characters. A space is treated as AND, and there are no other operators. You can switch to exact-phrase matching with search_type.
• Up to 10 Page IDs per search with search_page_ids.
• Active status defaults to active. You can ask for inactive or all, but inactive commercial ads are only there where the rules above keep them.
• Ad type is a filter, with the values ALL, EMPLOYMENT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS, HOUSING_ADS and POLITICAL_AND_ISSUE_ADS.
• Other filters include media type (image, meme, video, none), publisher platforms, languages and delivery date range.
• No translation. Search in the language of the ads.
• No batch download of creative. The reference says you cannot download a batch of archived ads. You can download the creative of an individual ad for analysis, and you must follow Meta's data storage terms.
• Rate limits. Error 613 means you have exceeded the rate limit for this API. Meta's reference does not give the numbers, so plan for retries.
• Some filters apply only to political ads. Bylines, delivery by region and estimated audience size are only available for POLITICAL_AND_ISSUE_ADS.

One more point. Meta stopped delivering social issue, electoral and political ads in the EU on 6 October 2025, according to reporting on its announcement, so for the EU the political-ad data stops there. It remains for earlier ads and for other markets.

What do you need for access?

The reference does not walk through setup, so we are relying on third-party documentation here, and you should check Meta's current requirements before you plan around it.

Adverity's data connector guide lists these prerequisites:

1. Create an app in Meta for Developers and give your Facebook account a role on it.
2. Confirm your identity at facebook.com/id.
3. Wait about 48 hours for confirmation.

You also need a valid access token on every call. Meta's reference lists error 190 (invalid OAuth 2.0 access token) for calls that fail that check.

The point to take from this is that access is tied to a real person's verified identity, not only to a developer account. If you are building a commercial product that depends on it, expect some friction and plan for who owns that account.

What are your options for commercial ads?

If you need to see what competitors are running in a market outside the EU, you have four realistic routes.

1. Use the website by hand

The Ad Library at facebook.com/ads/library shows all active ads across Meta's products, to anyone, without a login. It works for a few competitors and a few ads. It does not keep anything and does not group copies. Our guide to seeing competitors' Facebook ads covers the method.

2. Use the API for what it covers

If your competitors target the EU, the API is a legitimate source of ad copy, reach and targeting choices. If you study political advertising, it is the right tool. Know what you are asking for, though. A request for US commercial ads will return nothing, and that is not a bug in your code.

3. Export from the public pages with a tool

Several tools read what the public Ad Library website shows and give you structured data. Our own team built the Meta Ad Library actor on Apify, which has 3,739 users and 209,903 runs. These tools do not use the official API, and they are pulling from the same public view you see in a browser. That means no spend or performance numbers, and the same limit on inactive ads. Check Meta's terms and decide what is right for your use before you build on any of them.

4. Use a tracker that keeps history

This is the route we took. Seercraft tracks the brands you choose in the public Meta Ad Library across Facebook, Instagram, Messenger and Audience Network, checks them daily and keeps the history after ads stop. It also groups copies of one creative into one idea with a version count, and Seer writes a cited read of each brand where every claim links to the ads behind it.

Pick by job, not by tool. If you need data in your own warehouse, the Apify route is the one for you. If you need to understand competitors and brief creative from what you find, a product like Seercraft saves the glue work.

A quick check before you build

Ask these before you spend a week on API code.

• Are the ads I want delivered in the EU or about politics? If not, the API will not return them.
• Do I need spend or ROAS? Nobody outside Meta has it for commercial ads, except for EU reach figures and political ad ranges.
• Do I need history? Check the retention rules for the type of ads you want.
• Who will own the verified account behind the access token?

Sources

• Meta Ad Library API: Ads Archive reference (Meta for Developers)
• Archived Ad reference, fields (Meta for Developers)
• Meta Ad Library tools (Meta Transparency Center)
• What is the Meta Ad Library and how do I search it? (Meta Help Center)
• Collecting data from Facebook Ad Library (Adverity docs), for identity confirmation steps
• Meta blocks political ads in EU as TTPA regulation takes effect (PPC Land)

Add a competitor and start your free trial without writing any API code. Every subscription includes a 7-day free trial; see our pricing page for current plans and limits.