Facebook Ad Library API: Access, Parameters and Limits (2026)

Meta AdsCompetitor Research
Facebook Ad Library API: Access, Parameters and Limits (2026)

The short answer

  • The Meta Ad Library API is a Graph API endpoint called ads_archive. You call it with an access token and at least one country in ad_reached_countries.
  • You need a Facebook account with confirmed identity, a developer account and an app before the token works.
  • It returns full data for political and social-issue ads and for ads shown in the EU and UK. For ordinary commercial ads shown elsewhere, such as a US sneaker ad, you get little or nothing.
  • It returns text and a link to a rendered snapshot of each ad. It does not hand you image or video files.
  • If you only want to look at a competitor's ads, you do not need the API. The Meta Ad Library website, or the free brand pages in the Sprites ads library, get you there without code.

Most people who search for the Facebook Ad Library API want one of two things: a spreadsheet of competitor ads, or a feed of ads for a research project. The API can do the second well and the first only in some countries. This guide covers how access works, the parameters that matter, what comes back, and where it stops.

What the Meta Ad Library API is

The Meta Ad Library is the public archive of ads running across Facebook, Instagram, Messenger, Audience Network and Threads. The web version at facebook.com/ads/library is what most marketers use. The API is the same archive exposed as a query endpoint so that researchers, journalists and developers can pull results in bulk.

Meta built it for transparency, and that purpose decides what it holds. In Meta's own description, the archive covers ads about social issues, elections or politics everywhere it operates, plus all ads that were delivered in the European Union and the United Kingdom. Commercial ads in the rest of the world appear on the website while they are active, but the API is not designed to serve them in bulk.

How to get access

  1. Confirm your identity. Meta requires the Facebook account that uses the API to complete identity confirmation, which involves government ID, and to have two-factor authentication on. Allow time for review.
  2. Register as a developer. Create a Meta for Developers account on the same login.
  3. Create an app. Any app type will do for read-only Ad Library queries. You do not need to submit it for app review for this endpoint.
  4. Generate an access token. The Graph API Explorer gives you a short-lived user token in one click. For anything that runs more than once, exchange it for a long-lived token or use an app token, and keep it in a secrets store, not in a script.
  5. Make a first call. A request to /ads_archive with a token, a search term and a country is enough to confirm access works.

If the call returns an error about permissions or an unconfirmed identity, the account has not finished step 1. That is the most common blocker, and it has nothing to do with your code.

The parameters that matter

These are the ones you will use on almost every request. Meta's Ad Library API documentation lists the full set and can change, so treat this as the working core.

ParameterWhat it does
ad_reached_countriesRequired. The countries the ads were shown in, as two-letter codes. Match them to the data you are after, as the next sections explain.
search_termsKeywords to match in the ad text. Good for topics, weak for one specific brand.
search_page_idsOne or more Page IDs. This is how you pull one advertiser's ads.
ad_typeAll ads or only political and issue ads. Leaving it on the default is the usual choice for EU and UK research.
ad_active_statusActive, inactive or all. Use all if you want history for the countries that keep it.
ad_delivery_date_min / maxFilters by when delivery started, to slice a window.
fieldsThe columns you want back. Ask for only what you need.
limitPage size. Results come back in pages with a cursor you follow to get the next one.

Because the country is required, the single most useful habit is to match it to the data you are after. A search on a US-only brand with ad_reached_countries=US will usually return nothing for non-political ads, and people read that as a broken query. It is working as designed.

What the API returns

Common fields include the ad's ID, the Page name and ID, the creation and delivery start and stop times, the ad text (body, link title, description), the platforms it ran on, the languages, and an ad_snapshot_url. That last field links to Meta's rendering of the ad. Opening it needs a valid token, so it is not a public image URL you can embed.

What else you get depends on the type of ad:

Ad typeExtra data
Political and social-issue adsSpend and impressions as ranges, the paying entity, and demographic and regional breakdowns of who saw the ad. Kept in the archive for years.
Ads shown in the EU and UKTotal reach, reach by age, gender and country, the targeting the advertiser chose (ages, gender, locations), and who paid or benefited.
Ordinary commercial ads elsewhereNot served in bulk through the API.

Notice what is missing everywhere: exact spend for commercial ads, click-through rate, conversions and any measure of whether an ad is working. Meta does not publish those for anyone's ads. The closest proxy for a commercial ad is how long it has been running, which you can work out from the start and stop dates.

A first request, in plain terms

The shape of a call is a GET to the ads_archive edge on the Graph API, with the token, the countries, the terms or Page IDs, and the fields. In words: ask for ads that reached Germany and France, whose text mentions a keyword, that are still active, and return the Page name, the text, the start date, the platforms and the snapshot link, twenty per page.

Then loop. The response carries a paging block with a cursor. Keep requesting until it runs out, and write each page to disk as you go so a failure at page 40 does not cost you pages 1 to 39.

Limits to plan around

  • Rate limits. Graph API calls are throttled per app and per user. Meta does not publish one fixed number for this endpoint, and broad queries with many fields are the first to be slowed or refused. Back off on errors, use small pages, and narrow your date range.
  • Identity and token upkeep. Tokens expire. A job that worked in March can fail in May for that reason alone.
  • Keyword search is not exact. It matches text in the ad, not the advertiser. For a brand, search by Page ID.
  • Creative files. You get a snapshot link and text, not a downloadable image or video. If you need creative assets for analysis, you are scraping the website, which has its own terms and rate limits.
  • Coverage can change. Meta adjusts what the archive holds and how long it keeps it. Check its Business Help Center before you build a pipeline that depends on a field.

When the API is the right tool

  • Political or issue-ad research in any country: spend ranges, funders and demographic reach.
  • EU and UK market studies where you want targeting and reach for ordinary ads, such as how a fintech brand targets Germany versus France.
  • Monitoring a keyword across countries on a schedule and alerting on new advertisers.

It is the wrong tool for a marketer who wants to see what a US competitor is running this week. For that, the website is faster and complete.

The no-code route

For the common job, which is "show me what this brand runs", use one of these:

  1. The Meta Ad Library website. Search the brand, open its Page, and read every active ad with its start date. The steps are in how to see competitors' Facebook ads.
  2. The Sprites ad library pages. Brand pages live at /{brand}-ads, for example Nike ads, Glossier ads and Gymshark ads, and category pages cover whole industries, such as ecommerce ads and SaaS ads. They are free to read, so you can compare brands without a token, a script or a spreadsheet.
  3. A platform view. The Meta ads library hub groups Facebook and Instagram ads by brand and category in one place.

If you need history and a larger archive than Meta shows, the Facebook ad spy tools guide compares the paid options, and the Facebook Ad Library alternatives post covers what the library lacks.

Where Sprites fits

Sprites is an AI ads agent with a public ads library attached. The library is where you research: open a brand's page, read its ads, and see which have run longest. The agent is where you act on it: it audits your Meta, Google and other accounts, drafts new ads and stages every change for your approval. If you want the research without building a pipeline, start at the ads library. See pricing for the agent.

Frequently asked questions

Is the Facebook Ad Library API free?

Yes. Meta does not charge for the Ad Library API. You pay with setup: identity confirmation, a developer account, an app and a token that you have to keep refreshed.

Does the Ad Library API show ad spend?

Only for political and social-issue ads, and only as a range. For ordinary commercial ads Meta publishes no spend at all, in the API or on the website. In the EU and UK you get reach and targeting instead.

Why does my Ad Library API query return no results?

Usually because the ads are commercial and were not shown in the EU or UK, so the endpoint does not serve them in bulk. Other causes are a wrong country code, searching a brand name instead of a Page ID, an expired token, or an account that has not finished identity confirmation.

Can I download ad images and videos with the API?

No. You get the ad text and an ad_snapshot_url that renders the ad for a signed-in token. The image and video files are not returned as downloads.

How do I find a competitor's Page ID?

Open the competitor's Page in the Meta Ad Library website. The Page ID appears in the address bar of the results as the view_all_page_id value. Use it as the search_page_ids parameter.

What is the easiest way to see a competitor's Facebook ads without code?

Use the Meta Ad Library website, or open the brand's page in the Sprites ads library at /{brand}-ads. Both show current ads with no account and no token.

Whose ads do you want to see next?

Search any brand's ads (Nike, Canva, Ro...)