The Meta Ad Library API: who can use it, how to get access and what it returns

What the API covers, and the common misunderstanding

The misunderstanding is that the API is the Ad Library website in machine-readable form, so it must hold every ad running anywhere. It does not. Meta's Ad Library API page, as it read on 9 October 2026, describes two groups of ads you can search:

• Ads about social issues, elections or politics that were delivered anywhere in the world during the past seven years.
• Ads of any type that were delivered to the UK or the EU during the past year.

The same page sends anyone who wants to search all ads currently running to the library website instead. The note on the country parameter makes the limit explicit: an ad that did not reach any EU location is returned only if it is about social issues, elections or politics.

In practice that means a brand that advertises only in Australia, the United States or Canada has no ordinary ads in the API at all. If the same brand also delivers ads in Ireland, Germany or the UK, those ads are there. Meta's page says the API is available in every country where the Ad Library has launched, which it puts at more than 100, but that describes where you can use it from, not which ads it holds.

One recent narrowing: the release notes for 6 October 2025 say the political ad type can no longer be combined with EU countries in a search. The background is in our post on Meta's EU political ads decision.

Who can use it, and the access steps Meta lists

Meta does not restrict the API to researchers or to advertisers. Its page says you need a Facebook account to be authorised, and then lists three steps.

1. 01

   Confirm your identity and location

   You go through the same confirmation Meta requires of people who run ads about social issues, elections or politics, even if you never plan to run one. Meta says checking what you submit can take a few days.
2. 02

   Create a Meta for Developers account

   Creating the account means agreeing to Meta's developer terms, which its page calls the Platform Policy.
3. 03

   Add an app

   From the API page you open Meta's developer tools and create a new app. Queries are made on behalf of that app.

You also need an access token. Meta's page says a user access token requires you to be logged in and to give your app permission to obtain it. The release notes add a condition dated 23 April 2021: the person making queries must have a role on the app, or be given one by the app's owner.

Meta is plain that this is a tool for people comfortable with some programming. Its page suggests the Ad Library Report as a simpler starting point for research, and mentions that an ad blocker can stop queries from running.

What a request looks like

This is an illustrative example only, built from the sample on Meta's API page and its ads_archive reference. It asks for political and issue ads containing the word "california" that reached people in the United States. The version and the token are placeholders; never paste a real token into a document, a chat or a shared file.

https://graph.facebook.com/<API_VERSION>/ads_archive?search_terms='california'&ad_type=POLITICAL_AND_ISSUE_ADS&ad_reached_countries=['US']&fields=page_id,page_name,ad_snapshot_url&access_token=<ACCESS_TOKEN>

The response is a list of ads with the fields you asked for, plus a link to the next page of results. Meta's page says a search returns everything that matches, with at most 5,000 ads on each page.

The main search parameters

The reference lists sixteen parameters. These are the ones most people would use. The country parameter is marked as required.

Three more work only for political and issue ads: the "paid for by" byline, delivery by region, and estimated audience size. Meta's page warns that using a parameter that is not valid for the type of ad you are querying returns an error.

What comes back, by ad type

The fields are set out in Meta's archived ad reference. They fall into three tiers.

• Every available ad: the Library ID, the Page name and ID, the ad's text, link titles, captions and descriptions, creation time, delivery start and stop times, languages, the platforms it appeared on, and a snapshot link that displays the ad itself.
• Political and issue ads only: spend and impressions as ranges, the currency, the funding byline, estimated audience size, and reach split by age, gender and region.
• Ads delivered to the EU or UK: estimated reach, the age, gender and location targeting the advertiser chose, and a reach breakdown by age, country and gender. The beneficiary and payer are returned for EU delivery only.

No field reports clicks, conversions or return for any ad. We have set this out row by row in does the Meta Ad Library show spend, so we will not repeat the table here.

Two details matter if you were hoping to collect creative in bulk. The images and video are not returned as files; you get the snapshot link. And Meta's field notes say you cannot currently download a batch of archived ads, though you can download the creative for an individual ad, for analysis, subject to the data storage terms in its Terms of Service.

Rate limits and terms of use

Meta does not publish a number for this API. The ads_archive reference lists an error, code 613, for calls that have exceeded the rate limit, without saying what the limit is. Meta's general Graph API rate limiting page does not mention the Ad Library API, and says that Meta does not reveal the actual call counts allowed per user. So plan on finding the ceiling by running into it.

On use of the data, the Meta Platform Terms (last updated 3 February 2026) apply to anything obtained through Meta's developer platform. Among other things they prohibit selling, licensing or purchasing that data, and they let Meta suspend an app's access to APIs it has not used within a 28-day period. The API page itself says researchers and journalists may publish reports and articles based on the API, and that processed or analysed data can be shared publicly. Sharing the underlying data with other researchers or journalists is allowed, according to the page, if they have completed the same identity confirmation, have a developer account and have agreed to the same terms.

Is it worth your time?

It probably is if one of these describes you:

• You study or report on political and issue advertising, where the API gives spend and impression ranges going back seven years.
• Your competitors advertise in the EU or UK, and you want their ads, reach and targeting in a spreadsheet instead of a browser tab.
• You want to check a fixed list of Pages on a schedule and are comfortable writing a small script.

It probably is not if:

• Your competitors advertise only outside the EU and UK. Their commercial ads are not in the API, however good your code is.
• You want performance data. It is not there for anyone.
• You only need to look at a handful of advertisers now and then. The library website does that with no identity check and no app.

For the manual route, see the Meta Ad Library guide and our routine for seeing competitor ads on each platform.

Sources

All pages were opened and read on 9 October 2026.

• Meta, Ad Library API page, including its frequently asked questions (undated)
• Meta, Ad Library API release notes (latest entry 6 October 2025)
• Meta for Developers, Ads Archive reference, Graph API v26.0 (undated)
• Meta for Developers, Archived Ad reference, Graph API v26.0 (undated)
• Meta for Developers, Graph API rate limiting overview (undated)
• Meta for Developers, Meta Platform Terms (last updated 3 February 2026)