Meta Ad Library API: Access, Fields & Limits (2026)
How the Meta (Facebook) Ad Library API works: access steps, ads_archive fields, a working curl request, error codes, coverage limits, and scraping vs API.


A practical guide to the Meta (Facebook) Ad Library API, built on Meta's own reference docs: how to get access, what the ads_archive endpoint returns, a working request, the errors you'll hit, and where the API stops being useful for commercial ad research.
TL;DR: The Meta Ad Library API is the ads_archive endpoint of the Graph API. It's free, read-only, and needs a user access token from someone who has confirmed their identity with Meta. The big limitation: per Meta's reference, ads that did not reach any location in the EU are only returned if they are about social issues, elections, or politics. So for a US-only commercial brand, the API usually returns nothing. Spend and impression ranges exist only for political and issue ads.
People searching "facebook ad library api" usually want one of two things: a way to pull competitor ads into a spreadsheet or tool, or a way to monitor political advertising. The API is built for the second job and partly serves the first, mainly through EU-delivered ads that Meta has to disclose under the EU Digital Services Act.
This guide sticks to what Meta documents. Where the docs are silent, we say so.
💡 New to the Ad Library itself? Start with our Meta Ad Library guide or the Facebook Ad Library 2026 guide, which cover what the public website shows by region and ad type.
What is the Meta Ad Library API?
The Meta Ad Library API (also called the Facebook Ad Library API) gives programmatic, read-only access to ads stored in the Meta Ad Library. You query one Graph API endpoint, ads_archive, with search terms or Page IDs and a list of countries, and get back a list of ArchivedAd objects with the fields you request.
Key facts from Meta's reference docs:
- Endpoint:
https://graph.facebook.com/<VERSION>/ads_archive. The reference is published for Graph API v27.0 at the time of writing. - Read only. The ArchivedAd reference states that creating, updating and deleting are not supported.
- Free. There's no paid tier. Access is gated by identity confirmation, not payment.
Who can access the Ad Library API?
Meta's Ad Library API page lays out the access path. In short:
- Confirm your identity and location with Meta (done from your personal Facebook account at facebook.com/ID). This is the same kind of check Meta asks of people who run ads about social issues, elections, or politics, and it can take some time to clear.
- Create a Meta for Developers account at developers.facebook.com and create an app.
- Generate a user access token for that app (the Graph API Explorer is the quickest way to get one for testing) and pass it as
access_token.
Two practical notes. First, the token has to belong to the person who completed identity confirmation. Second, default user tokens are short-lived and expire in hours. For a script that runs on a schedule, exchange it server-side (it needs your app secret) for a long-lived token, which per Meta's long-lived token docs generally lasts about 60 days, and plan to refresh it before then.
What does the API actually return?
This is where most guides overpromise. Coverage depends on where the ad was delivered and whether it's a political or issue ad.
Which ads you can query
The ads_archive reference says it plainly: ads that did not reach any location in the EU will only be returned if they are about social issues, elections, or politics.
Meta's Ad Library API page words the scope a little more broadly: ads about social issues, elections or politics delivered anywhere in the world during the past seven years, and ads of any type delivered to the United Kingdom (UK) or European Union during the past year. So UK-delivered commercial ads from the last year are in scope too, even though the reference only mentions the EU.
In practice:
| Ad | Returned by the API? |
|---|---|
| Political, election or social issue ad, any country | ✅ Yes |
| Commercial ad that reached at least one EU country (or the UK, past year) | ✅ Yes |
| Commercial ad delivered only outside the EU and UK (e.g. US-only) | ❌ No |
That last row is the one that surprises people. The public Ad Library website shows active commercial ads from every country, but the API doesn't expose that same set.
Fields available on every returned ad
From the ArchivedAd reference:
id(the Library ID),page_id,page_namead_creation_time,ad_delivery_start_time,ad_delivery_stop_timead_creative_bodies,ad_creative_link_titles,ad_creative_link_descriptions,ad_creative_link_captions(the copy on each card)ad_snapshot_url(a URL that renders the archived ad)languages,publisher_platformstotal_reach_by_location(estimated reach, for EU, UK and Brazil locations)
If you don't pass a fields parameter, you only get a handful of defaults (such as id, page_id, delivery times and ad_snapshot_url). Always list the fields you need.
Fields for EU and UK ads
eu_total_reach: estimated reach across EU locations (EU only)beneficiary_payers: who the ad says benefits from and pays for it (EU only)age_country_gender_reach_breakdown: reach by age, country and gendertarget_ages,target_gender,target_locations: the targeting the advertiser chose
The last four are documented for UK and EU ads, plus political and issue ads in Brazil.
Fields for political and issue ads only
spendandimpressions, both returned as ranges, not exact numberscurrency,bylines(who paid for the ad),estimated_audience_sizedemographic_distributionanddelivery_by_region(reach split by age/gender and by region)br_total_reach(political and issue ads delivered to Brazil)
There is no field for spend or impressions on commercial ads, in any region. If a tool claims to show exact spend for a competitor's commercial Meta ads "from the Ad Library API", that number isn't coming from Meta's API.
Key parameters
From the ads_archive reference:
| Parameter | What it does |
|---|---|
ad_reached_countries | Countries the ad reached, as ISO codes (or ALL). Marked required; always include it. |
ad_type | ALL (default), POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, EMPLOYMENT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS |
search_terms | Keyword search, 100 characters max. Not translated, so search in the ad's language. |
search_type | KEYWORD_UNORDERED (default) or KEYWORD_EXACT_PHRASE |
search_page_ids | Up to 10 Facebook Page IDs |
ad_active_status | ACTIVE (default), INACTIVE, ALL |
ad_delivery_date_min / ad_delivery_date_max | Date window, YYYY-mm-dd, inclusive |
publisher_platforms | e.g. FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, THREADS |
media_type | ALL, IMAGE, MEME, VIDEO, NONE |
languages | ISO 639-1 language codes |
bylines, delivery_by_region and the estimated_audience_size_min/_max filters only work with POLITICAL_AND_ISSUE_ADS.
To search one advertiser, search_page_ids is more reliable than a keyword. If you don't know a brand's Page ID, our free Facebook Page ID Finder looks it up.
A minimal example request
Pull active ads from one Page that reached Germany, with the copy and EU reach fields:
curl -G \
-d "search_page_ids=[\"<PAGE_ID>\"]" \
-d "ad_reached_countries=[\"DE\"]" \
-d "ad_type=ALL" \
-d "ad_active_status=ACTIVE" \
-d "fields=id,page_name,ad_delivery_start_time,ad_creative_bodies,ad_creative_link_titles,ad_snapshot_url,publisher_platforms,eu_total_reach" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<VERSION>/ads_archive"
Replace <VERSION> with a current Graph API version (for example v27.0), <PAGE_ID> with the advertiser's Page ID, and <ACCESS_TOKEN> with your token. Never commit a real token to a repo or paste it into a shared doc.
The response has two parts:
data: a list of ads with the fields you asked forpaging: cursors and anextURL. Keep followingnextuntildatacomes back empty, which Meta's docs say marks the end of the result set.
For a political-ad keyword search, Meta's own example uses search_terms='california', ad_type=POLITICAL_AND_ISSUE_ADS and ad_reached_countries=['US'].
Common errors and what they mean
The ads_archive reference lists these error codes:
| Code | Meaning | Usual fix |
|---|---|---|
190 | Invalid OAuth 2.0 access token | Token expired or malformed. Generate a new one or exchange for a long-lived token. |
100 | Invalid parameter | Check spelling and allowed values, especially enums like ad_type. |
1009 | Failed to pass parameter validation | Often an array formatted wrong (e.g. countries not passed as a list) or a missing required parameter. |
2500 | Error parsing graph query | Usually a malformed fields list or URL encoding issue. |
613 | Calls to this API have exceeded the rate limit | Slow down, back off, and retry later. |
Two non-errors that look like bugs:
- Empty
datafor a brand you can see on the website. If the brand's ads ran only outside the EU and aren't political or issue ads, the API won't return them. That's coverage, not a broken query. - Keyword search misses obvious ads. Search terms aren't translated. A German-language ad won't match an English keyword.
Meta doesn't publish a fixed call quota for ads_archive in the reference; you find out you've hit it via error 613. Build in backoff and cache results rather than re-querying the same Pages.
Can you download ad creatives through the API?
Partly. The API gives you ad_snapshot_url, which renders the archived ad with its uncompressed images and video. The ArchivedAd reference also states that batch downloads aren't supported, and downloading an individual ad's creative is allowed for analysis only, under the data storage terms in Meta's Terms of Service.
If you only need to save a handful of ads, it's faster to skip the API entirely. Skaler's free Facebook Ad Downloader saves the video or image from a single Ad Library ad link.
Ad library scraper vs the official API
Many "ad library scraper" tools exist because the API doesn't cover commercial ads outside the EU. Before you build or buy one, know the trade-offs:
- Terms. Meta's Automated Data Collection Terms say you will not engage in automated data collection without Meta's express written permission. Scraping the Ad Library website can put the account and IP you use at risk. We don't cover techniques for getting around Meta's protections, and you shouldn't rely on a vendor that markets that as a feature.
- Fragility. The website's markup and internal requests change without notice. A scraper that works this month can silently return partial data next month.
- Same data ceiling. A scraper can only see what the public site shows. For commercial ads outside the EU, UK and Brazil, that's the creative, the Page and the start date. It still can't show you spend or performance.
- The API is stable and documented. If your use case fits its coverage (EU-delivered ads, political and issue ads), use the API.
When a tool is easier than the API
The API makes sense if you're a researcher, a journalist tracking political ads, or a team building something on EU ad data. For day-to-day creative research it's often more work than it's worth: identity confirmation, token refresh, pagination, no commercial coverage outside the EU, and no performance data.
Skaler shows which Meta ads are winning and why — hooks, angles, formats, ROAS — plus competitor ad intel and bulk launching. Works in a dashboard or via MCP. If you work in Claude or another AI assistant, Skaler's Meta Ads MCP lets you ask those questions in chat. (New to MCP? Our guide to connecting Meta's official Ads MCP to Claude explains how MCP servers plug into Claude.) For one-off jobs, the free tools hub has the ad downloader, Page ID finder and more, no API setup needed.
Skaler doesn't offer a public REST API, so if you specifically need raw JSON in your own pipeline, Meta's ads_archive endpoint is the route.
Frequently Asked Questions
Is the Meta Ad Library API free?
Yes. There's no charge to use the ads_archive endpoint. You need a Meta for Developers account, an app, and a user access token from someone who has confirmed their identity with Meta.
Does the Facebook Ad Library API return commercial ads? Only some. Per Meta's reference, ads that did not reach any location in the EU are only returned if they're about social issues, elections, or politics. Commercial ads that reached an EU country are returned; US-only commercial ads are not.
Can I get ad spend from the Ad Library API?
Only for political and issue ads, and only as ranges. The spend and impressions fields are documented for POLITICAL_AND_ISSUE_ADS only. For EU ads you get estimated reach (eu_total_reach) instead.
What is the rate limit for the Ad Library API?
Meta's ads_archive reference doesn't publish a fixed number. When you exceed the limit, calls fail with error code 613. Add backoff and caching to stay under it.
Why does the API return an empty result for a brand I can see in the Ad Library?
Most likely the brand's ads didn't reach any EU country and aren't political or issue ads, so they're outside the API's coverage. Also check that ad_reached_countries includes a country the ads ran in and that your keyword is in the ad's language.
Is it legal to scrape the Facebook Ad Library? We can't give legal advice. Meta's Automated Data Collection Terms require Meta's express written permission before any automated data collection, so scraping carries account and terms risk. The official API is the sanctioned route for the data it covers.
How do I find a Facebook Page ID to search one advertiser?
Use a free lookup such as Skaler's Facebook Page ID Finder, or open the advertiser in the Ad Library and copy the view_all_page_id value from the URL.
The takeaway
The Meta Ad Library API is a clean, documented, free way to pull EU-delivered ads and political and issue ads with real reach and targeting data. It is not a back door to every commercial ad on Facebook. Check coverage before you build, request explicit fields, handle paging and error 613, and treat ad_snapshot_url downloads as analysis-only.
Related Resources
- Meta Ad Library guide: search, filters and limits
- Facebook Ad Library in 2026: What Meta Actually Shows You (and What It Hides)
- Meta Ads Library: The Complete Guide to Analyzing Competitor Ads
- How to Connect the Official Meta Ads MCP to Claude
- Free Facebook Ad Downloader
- Free Facebook Page ID Finder
Related Articles

Meta Marketing API: Access, Tokens, Rate Limits & Insights (2026)
How to use the Meta (Facebook) Marketing API: get access, pick the right token, handle rate limits, pull reporting with the Insights API and create ads paused.

Meta Partnership Ads: Setup, Ad Codes & Permissions (2026)
How Meta partnership ads work: ad codes vs account-level permission, Ads Manager setup, placements, creator reporting, common errors and when to use them.
Follow on LinkedIn