Check website

The Meta Ad Library API: what you can pull

·4 min read

The Meta Ad Library API lets you query Meta's ad archive from code through one Graph API endpoint, ads_archive. To use it you confirm your identity at facebook.com/ID, create a Meta for Developers account and app, and send an access token with every request. The catch is coverage. The API returns political and social issue ads from anywhere, plus ads of any type delivered to the EU or UK, so an ordinary ad a competitor runs only in the US is not in it.

If your competitors sell in Europe, the API is a good research source. If they sell only in North America, it will mostly return nothing, and the web library or a tool built on it is the better route.

How to get Meta Ad Library API access

Meta's Ad Library API page lists three steps, and you need a Facebook account before any of them.

  1. Confirm your identity and location at facebook.com/ID. This is the same check Meta requires from people who run ads about social issues, elections or politics, and Meta says it can take a few days.
  2. Create a Meta for Developers account and agree to the Platform Policy.
  3. Go back to the API page, select Access the API, then create an app under My Apps.

Once the app exists, generate a user access token for it, for example in the Graph API Explorer, and pass it as access_token. Plan for the identity step to be the slow one.

The ads_archive endpoint and a sample request

Every query is a GET to https://graph.facebook.com/<API_VERSION>/ads_archive. The endpoint reference documents these parameters:

Parameter What it does
search_terms Keyword search, up to 100 characters
search_type KEYWORD_UNORDERED by default, or KEYWORD_EXACT_PHRASE
search_page_ids Up to 10 Facebook Page IDs, for one advertiser's ads
ad_reached_countries Country codes such as DE, or ALL
ad_type ALL, POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, EMPLOYMENT_ADS or FINANCIAL_PRODUCTS_AND_SERVICES_ADS
ad_active_status ACTIVE by default, or INACTIVE or ALL
ad_delivery_date_min, ad_delivery_date_max A delivery date range
publisher_platforms, media_type, languages Narrow by placement, format and language

Here is a request for active commercial ads that mention standing desks and reached Germany:

curl -G \
  -d "search_terms='standing desk'" \
  -d "ad_type=ALL" \
  -d "ad_reached_countries=['DE']" \
  -d "ad_active_status=ACTIVE" \
  -d "fields=page_name,ad_creative_bodies,ad_creative_link_titles,ad_delivery_start_time,publisher_platforms,eu_total_reach,target_ages,target_locations" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/ads_archive"

Ask for fields by name. The reference marks only a few as defaults, such as page_id, ad_snapshot_url and the delivery start and stop times, so a request without fields gives you links and dates but no ad text. Results are paged, so follow the paging.next URL until it runs out.

What fields the Ad Library API returns

What you get depends on which tier the ad falls in. The ArchivedAd reference labels each field.

Tier Fields
Every ad in the API id, page_id, page_name, ad_creative_bodies, ad_creative_link_titles, ad_creative_link_descriptions, ad_creative_link_captions, ad_delivery_start_time, ad_delivery_stop_time, ad_snapshot_url, publisher_platforms, languages
Political and issue ads only spend, impressions, currency, bylines, demographic_distribution, delivery_by_region, estimated_audience_size
EU ads only eu_total_reach, beneficiary_payers
EU and UK ads target_ages, target_gender, target_locations, age_country_gender_reach_breakdown

Spend and impressions stay political only. For a commercial ad delivered in Europe the best you get is estimated EU reach and the targeting the advertiser chose, which is still more than the web library shows for a US ad. There is no image or video file in the response either. ad_snapshot_url links to a rendered copy of the ad.

The big limit: which ads the API leaves out

The Meta Ad Library API only fully covers political and social issue ads and ads delivered in the EU or UK. Meta's API page says the API covers political and issue ads delivered anywhere in the past 7 years, and ads of any type delivered to the UK or EU in the past year. The endpoint reference puts it the other way round. Ads that did not reach any EU location come back only if they are about social issues, elections or politics.

In practice, a query for ad_reached_countries=['US'] with ad_type=ALL returns the political and issue ads and nothing else. A US-only competitor's sales ads never appear, even though you can see them in the web library at facebook.com/ads/library. The Meta Ad Library guide covers the web version and its retention rules, and the Facebook ad library search walkthrough covers searching it by hand.

So before you build a scraper or pipeline, decide which question you are asking. "What does this brand run in Germany, to whom?" is a good API question. "What does this brand run in the US?" is not.

Get a competitor's Meta ads without the API

Our Meta Ad Finder skips the identity check, the app and the token. Type a Facebook page name exactly as it appears on Facebook, or a keyword, and pick every country or one market, including the US. It reads the active ads in the Meta Ad Library and returns up to the 30 most recently started, listed longest-running first, each with its body text, headline, call-to-action button, landing page, format, platforms, start date, days running and a link to the ad in the library. A keyword search also lists the pages behind the ads.

It does not return spend, reach or targeting, stopped ads, or the images and videos themselves, and when Meta lists more than 30 ads the report says the rest fall outside the sample. A run costs 5 credits, and a search that finds no ads is refunded. If you need EU targeting data, the API is still the tool for that job.

Keep reading