Meta Ad Library API: what you can pull, access rules and limits
The Meta Ad Library API returns ads delivered in the EU, kept one year after their last impression, plus political or social-issue ads anywhere, kept 7 years. Commercial ads that never reached the EU don’t come back; spend and impressions are political-only.
| Field group | Which returned ads carry it | Fields (Meta Graph API reference v27.0) |
|---|---|---|
| Basic fields (13; four are sent by default) | Any ad the API returns | id, ad_creation_time, ad_creative_bodies, ad_creative_link_captions, ad_creative_link_descriptions, ad_creative_link_titles, ad_delivery_start_time, ad_delivery_stop_time, ad_snapshot_url, languages, page_id, page_name, publisher_platforms |
| Reach by location | Any returned ad, but reach is broken down only for the EU, Brazil and the UK | total_reach_by_location |
| Political and social-issue only | POLITICAL_AND_ISSUE_ADS | bylines, currency, delivery_by_region, demographic_distribution, estimated_audience_size, impressions, spend (plus br_total_reach for political ads in Brazil) |
| EU only | Ads delivered to the EU | beneficiary_payers, eu_total_reach |
| Targeting | Ads delivered in the EU; political ads delivered to the UK or Brazil. Meta labels these fields ‘UK & EU’, but a UK ad is returned only if it also reached the EU or is political | age_country_gender_reach_breakdown, target_ages, target_gender, target_locations |
How to pull ads from the Meta Ad Library API, step by step
Section titled “How to pull ads from the Meta Ad Library API, step by step”This page covers programmatic access only. The parameters below come from Meta's developer reference (v27.0), read on 15 November 2026.
- Get access. Every call needs an access token. Meta's Ad Library tools page says only that "authorized users" can use the API and links to facebook.com/ads/library/api. That page returned a 403 when we checked, so we can't confirm the sign-up steps.
- Call the endpoint. Send a GET to
https://graph.facebook.com/<VERSION>/ads_archivewith the token. The only required parameter isad_reached_countries(ALL or an ISO country code). The response hasdata(a list of ArchivedAd nodes) andpaging. Meta's own example pulls political ads that mention California and reached 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" - Write the search. In
search_terms, a space works as AND.search_typedefaults to KEYWORD_UNORDERED. KEYWORD_EXACT_PHRASE matches exact phrases, and you separate phrases that must all match with commas. Meta doesn't translate keywords, so search in the language the ads are written in. To follow specific advertisers, usesearch_page_ids. - Filter.
ad_active_statusdefaults to ACTIVE. Pass ALL or INACTIVE to include ads that are no longer eligible for delivery.ad_typetakes ALL (the default), EMPLOYMENT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS (which replaced CREDIT_ADS), HOUSING_ADS or POLITICAL_AND_ISSUE_ADS. You can narrow further withad_delivery_date_min/ad_delivery_date_max(YYYY-mm-dd),publisher_platforms,media_typeandlanguages. - Request the fields you need. Only ad_delivery_start_time, ad_delivery_stop_time, ad_snapshot_url and page_id are marked Default. List every other field in a
fieldsparameter. - Paginate to the end. Follow
paginguntildatacomes back empty. Meta says that marks the end of the result set.

Access rules: which ads the API actually covers
Section titled “Access rules: which ads the API actually covers”The Ad Library website lists all active ads running across Meta's products. The API is narrower. Meta describes it as a tool for deeper analysis of ads about social issues, elections or politics, plus ads delivered to the EU and associated territories; authorized users can also analyze active public branded content. The reference's note on ad_reached_countries spells it out: "Ads that did not reach any location in the EU will only return if they are about social issues, elections or politics."
The test is where the ad delivered, not where it was targeted or which country code you pass. A commercial ad that never delivered in the EU isn't returned, even while it is live on the website. An ad targeted at another country does come back if it logged EU reach.
Retention follows the same split:
- Political, election and social-issue ads: kept for 7 years, active or inactive.
- Ads with an EU impression: shown while active, then archived for one year after the last impression.
- Branded content: active public posts only.
Targeting data for political ads isn't in the API. It sits in a separate Ad Targeting dataset that is open only to approved researchers.

What the API returns, and what it withholds
Section titled “What the API returns, and what it withholds”Thirteen basic fields can be requested for any ad the API returns: creative text, link captions, descriptions and titles, creation and delivery times, platforms, languages, the Page and a snapshot URL that shows the creative. Four of them come back without asking (step 5). total_reach_by_location isn't limited by ad type, but it only breaks reach down for the EU, Brazil and the UK. You can't download archived ads in batches. You can download one ad's creative at a time, for analysis only and under Meta's data storage terms.
spend, impressions, estimated_audience_size and demographic_distribution exist only for POLITICAL_AND_ISSUE_ADS, and spend and impressions come as ranges, not exact values. The targeting fields (ages, gender, locations) carry Meta's label "UK & EU". Because a UK ad reaches the API only if it also delivered in the EU or is political, in practice you get targeting for EU-delivered ads and for political ads in the UK and Brazil.
There is no run-length field, so you count the days between ad_delivery_start_time and ad_delivery_stop_time yourself. Meta describes both as the times the advertiser wants delivery to start and stop, not measured delivery. The stop time is blank if the ad runs until the advertiser stops it or the budget runs out.

Rate limits and errors
Section titled “Rate limits and errors”Meta doesn't publish a numeric rate limit or a page size for the Meta ads library API, and the limit parameter isn't in the reference. The reference lists error 613 ("Calls to this api have exceeded the rate limit"), 190 for an invalid OAuth 2.0 access token, and 100, 2500 and 1009 for parameter and query errors. Retry with backoff when you get a 613.
The only documented caps are on inputs: search_terms takes up to 100 characters, and search_page_ids takes up to 10 Page IDs per call.

Using the API for competitor monitoring
Section titled “Using the API for competitor monitoring”Send competitors' Page IDs through search_page_ids, set ad_active_status and ad_reached_countries to ALL, and pass ad_delivery_date_min on each poll to catch new launches. Store what you pull yourself: inactive EU ads expire from the archive on the schedule above. This catches every ad of theirs that delivered in the EU or is political, and nothing else.
A Facebook ad library scraper reads the public website instead, which lists all active ads. It inherits the website's limits: commercial ads without EU delivery are visible only while they run, and come without spend. That is the trade-off with any Facebook ads library scraper compared with the API.
Our count: how few US-only Facebook ads are political
Section titled “Our count: how few US-only Facebook ads are political”On 15 November 2026 we counted Facebook launches dated 16 October to 14 November 2026 in Spytrend's database: 164,432,220 in total, of which 22,707,422 (13.81%) were targeted only at the US. Only 433,662 of those US-only ads (1.91%) carry Spytrend's AI category non_profit_politics_and_causes. That label is a proxy, not Meta's definition of social issues, elections or politics, and it exists only on ads that have been categorized. On this proxy, 98.09% of US-only launches have no political route into the API and come back only if they delivered in the EU.
The count does not show how many ads the API misses. We didn't count EU delivery among the US-only ads, and targeting doesn't decide it: 23.30% of all launches in the window carry an EU disclosure, including one ad targeted at India that listed EU reach in the Netherlands and Romania. All figures describe one commercial database, not Meta's own index.
Can I use the Meta Ad Library API for competitor ad monitoring?
Section titled “Can I use the Meta Ad Library API for competitor ad monitoring?”Partly. Polling a competitor’s Page IDs with search_page_ids returns their ads that delivered in the EU or are about social issues, elections or politics. Their commercial ads that never delivered in the EU don’t come back, even while those ads show on the Ad Library website.
How do I get Facebook Ad Library API access?
Section titled “How do I get Facebook Ad Library API access?”Meta’s Transparency Center says only that ’authorized users’ can use the API and links to facebook.com/ads/library/api. That page returned a 403 when we checked on 15 November 2026, so we can’t confirm the sign-up steps or how the access token every call requires is issued.
Does the Meta Ad Library API return spend and impressions?
Section titled “Does the Meta Ad Library API return spend and impressions?”Only for political and social-issue ads. Meta’s Archived Ad reference marks spend, impressions, estimated_audience_size and demographic_distribution as available only for POLITICAL_AND_ISSUE_ADS, and spend and impressions come as ranges.
What is the Meta Ad Library API rate limit?
Section titled “What is the Meta Ad Library API rate limit?”Meta doesn’t publish one. Its ads_archive reference lists error 613 for exceeding the rate limit but gives no quota, so build in retries with backoff instead of assuming a fixed allowance.
Is there a Google Ads Transparency Center API?
Section titled “Is there a Google Ads Transparency Center API?”We couldn’t verify one. Google’s help page for the Transparency Center returned a 404 when we checked on 15 November 2026, and the public site is adstransparency.google.com. Until Google documents it, treat claims about a Google Ads Transparency API, or about what a Google Ads Transparency Center scraper can reach, as unconfirmed.