parsly.to

// Guide · Meta

Meta Ad Library API: what it covers and how to get access

What Meta's free Ad Library API returns (political ads everywhere, every ad shown in the EU and UK), how to get access, its limits, and what to use for ordinary ads in the US and elsewhere.

Updated 22 Oct 2026 · 4 min read

The short answer

The Meta Ad Library API is free and returns ads about social issues, elections or politics from anywhere, plus ads of any kind shown in the EU or UK. To use it, confirm your identity at facebook.com/ID, create a Meta for Developers account and app, and call the ads_archive endpoint with an access token. Ordinary ads outside Europe aren't included.

Need a brand's US ads? Collect them from the library

The API skips ordinary ads outside Europe. Parsly collects them from the Ad Library page itself and downloads them as a spreadsheet.

Add to Chrome

The Meta Ad Library API is Meta’s official way to search the Ad Library from code. It’s free, and it’s built for researchers and journalists studying political ads and ads in Europe. Marketers often reach for it to pull a competitor’s ads, and find it skips most of them. This guide says what it covers, how to get in, and what to use instead.

What does the Meta Ad Library API cover?

Two kinds of ads: ads about social issues, elections or politics, from anywhere, for the past seven years; and ads of any type delivered to the EU or UK, for the past year. Ordinary ads shown only outside Europe aren’t included.

That’s Meta’s own summary on the Ad Library API page (checked October 2026). The endpoint’s reference puts it another way: “Ads that did not reach any location in the EU will only return if they are about social issues, elections or politics” (ads_archive). The reference names only the EU, while the API page and the field list include the UK. If UK ads matter to you, try a search with ad_reached_countries set to GB before building on it.

Two dates matter:

  • Meta stopped allowing political, electoral and social issue ads in the EU from 6 October 2025, citing new EU rules (Meta’s announcement). Older ones are still archived.
  • Meta’s help centre says EU and UK ads are kept for one year after their last impression, and political ads for seven years (About the Meta Ad Library).

What does it return for each ad?

Every ad has its Library ID, the Page that ran it, its text, link titles and descriptions, start and stop dates, platforms, languages, and an ad_snapshot_url that shows the ad on Meta’s site. Other fields depend on the ad.

Field Every ad EU and UK ads Political and issue ads
Text, headline, dates, Page, platforms, snapshot link Yes Yes Yes
Spend (spend, as a range) No No Yes
Impressions (as a range) No No Yes
Total reach No Yes (eu_total_reach, total_reach_by_location) Brazil only
Targeted ages, gender and locations No Yes Brazil only
Reach by age, gender and country No Yes Yes, as demographic_distribution
Who paid (beneficiary_payers) No EU only Funded-by line (bylines)

Source: Archived Ad fields. There’s no field for the image or video files, and none for likes, clicks or results.

How do I get access to the Ad Library API?

Confirm your identity with Meta, create a developer account and an app, then call the API with an access token. Meta lists three steps on its API page.

  1. Confirm your identity and location. Go to facebook.com/ID and follow the same checks Meta uses for people running political ads. Meta says this can take a few days.
  2. Create a Meta for Developers account. On Meta for Developers, choose Get started and accept the Platform Policy.
  3. Add an app. Back on the Ad Library API page, choose Access the API, then My apps and Create app.
  4. Get an access token for your app, for example from the Graph API Explorer, and call the endpoint:
curl -G \
  -d "search_terms='running shoes'" \
  -d "ad_type=ALL" \
  -d "ad_reached_countries=['DE']" \
  -d "fields=id,page_name,ad_creative_bodies,ad_delivery_start_time,ad_snapshot_url" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/ads_archive"

Results come back a page at a time; follow the paging link until data is empty. Meta also keeps an Ad Library API script repository on GitHub with examples and a command-line tool.

What are the limits?

  • Coverage. Ordinary ads outside the EU and UK aren’t returned, which rules out most US-only advertisers.
  • Tokens expire. User tokens from the Explorer last hours; long-lived ones about 60 days (Meta’s token guide), then you need a new one.
  • Rate limits. Meta doesn’t publish a number on the endpoint’s page; when you hit one, you get error 613, “Calls to this api have exceeded the rate limit”.
  • Search. search_terms takes up to 100 characters, and search_page_ids up to 10 Pages per call.
  • No media files and no results: no images or videos to download, no clicks or sales.
  • Spend only for political and issue ads.

Useful filters: ad_type (ALL, POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, EMPLOYMENT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS), ad_active_status (ACTIVE, INACTIVE, ALL), media_type, publisher_platforms, languages, and ad_delivery_date_min and _max.

What can I use for ordinary ads outside Europe?

The Ad Library website itself, which shows every ad running anywhere. The choice is how you get them out of it.

Way Cost Ordinary US ads Needs code What you get
Ad Library API Free No Yes Data, plus reach and targeting for EU and UK ads
Ad Library website, by hand Free Yes, while running No What you copy down
Paid scraping services (such as Apify actors or ScrapeCreators) Pay as you go Yes Some Data from the public library
Parsly Free Yes, while running No A spreadsheet, with likely winners marked

Scraping services read the public website for you, so check their terms and Meta’s before relying on one.

How do I get a brand’s ads without the API?

Parsly is a free Chrome extension that collects ads straight from the Ad Library page, any country, no developer account.

  1. In the Ad Library, search for the brand and pick it from the advertiser list.
  2. Open Parsly from Chrome’s toolbar. The first time, allow it on facebook.com.
  3. Click Collect. Parsly scrolls the page like a person would and reads every ad: text, dates, versions, format, landing page and media links.
  4. See the likely winners (the ads running longest, with the most versions), then download a spreadsheet (CSV).

Like the API, it can’t see spend on ordinary ads, because Meta doesn’t publish it. For the website itself, see how to use the Meta Ad Library.

Questions people ask

Is the Meta Ad Library API free?

Yes. There's no charge to use it. You need a Facebook account, a confirmed identity and a Meta for Developers app.

Does the Meta Ad Library API include US ads?

Only ads about social issues, elections or politics. Ordinary commercial ads that were only shown in the US, or anywhere outside the EU and UK, don't come back from the API, though they're on the Ad Library website while they run.

Does the API return spend?

Only for political and issue ads, as a range, with impressions as a range too. Ordinary ads, even European ones, have no spend field; European ones have reach and targeting instead.

How long does getting access take?

Meta says confirming your identity and location can take a few days. Creating the developer account and app takes minutes once that's done.

Can I get the ad images and videos from the API?

Not as files. Each ad comes with an ad_snapshot_url, a link that shows the ad on Meta's site, plus its text, headline, dates and platforms.

Are UK ads in the API?

Meta's Ad Library API page says ads of any type delivered to the UK or EU in the past year are included, and its field list has UK reach and targeting. One note in the endpoint's reference still mentions only the EU, so test a UK search before relying on it.

Sources

Checked against the real sites on 22 October 2026. Platforms change their buttons often; if something has moved, tell us at [email protected].