Data access
What the Meta Ad Library API returns, and what it leaves out
By Jackson Gathondu. Published 1 November 2026. Updated .
The Meta Ad Library API is Meta's official way to query its Ad Library from code. It was built for transparency, so it returns Ads about social issues, elections or politics anywhere, plus Ads delivered in the EU. A commercial Ad that ran only in the US, Canada or Australia is not in it.
Below are the Ads and fields the API returns as of 1 November 2026, the steps to get access, and a way to read a competitor's commercial Ads outside Europe.
Which Ads the API returns
From Meta's Graph API reference for the ads_archive endpoint (v26.0), checked 1 November 2026.
| Ad | In the API? | What Meta says |
|---|---|---|
| Ads about social issues, elections or politics, any country | Yes | Returned for every country you search, with spend, impressions and audience ranges. |
| Commercial Ads that reached anyone in the EU | Yes | Returned, with EU reach and the payer and beneficiary. Meta keeps them for one year after their last impression. |
| Commercial Ads that never reached the EU | No | Meta's wording: Ads that did not reach any location in the EU will only return if they are about social issues, elections or politics. |
| Housing, employment and financial products Ads | Only under the rules above | They are ad_type filters. They narrow a search but do not open up non-EU commercial Ads. |
Which fields come back, and for which Ads
Even for an Ad the API does return, many fields are filled only for political and issue Ads or for Ads in the EU and UK.
| Field | Filled for |
|---|---|
| spend, impressions, demographic_distribution, delivery_by_region | Political and issue Ads only |
| eu_total_reach, beneficiary_payers | Ads delivered to the EU only |
| target_ages, target_gender, target_locations, age_country_gender_reach_breakdown | Ads delivered to the UK and EU, and political and issue Ads delivered to Brazil |
| ad_creative_bodies, ad_snapshot_url, ad_delivery_start_time, ad_delivery_stop_time, page_name, publisher_platforms | Every Ad the API returns |
How to get access to the official API
These are the steps on Meta's Ad Library API page, checked 1 November 2026.
Confirm your identity and location
Use a Facebook account and complete identity and location confirmation at facebook.com/ID. Meta says this can take a few days. It is a separate check from verifying a developer account.
Create a developer account and an app
Register at Meta for Developers and create an app. The app is what holds your access token.
Get an access token and query ads_archive
Generate a user access token and call the ads_archive endpoint with search_terms (100 characters at most) or search_page_ids (up to 10 Pages), plus ad_reached_countries. Calls past the rate limit fail with error 613.
What that leaves out for commercial Ad research
Most brands researching competitors want commercial Ads in their own market: a protein powder Ad in the US, a budgeting app Ad in Canada. If that Ad never ran in the EU, the API does not return it, even though Meta's public Ad Library website shows it to anyone who searches.
When the API does return a commercial Ad, it has no spend or impressions. You get the copy, a snapshot link, start and stop dates and placements. For commercial Ads, what you can measure is how long an Ad has run, whether it is still active and how many versions of it the Advertiser has made.
Search terms are not translated, so you search in the language of the Ads you want. The API also has no analysis of the creative. You read each video yourself to find its hook, offer and format.
Data limits
Data limits that apply here
- Meta discloses no spend, impressions or reach for commercial Ads, in the API or on the public Ad Library website. ShortsIntel returns those fields as null for commercial Ads too.
- ShortsIntel reads Meta's public Ad Library, so it returns only what that library shows. Ads Meta has removed or never published there are not available.
- Ad analysis on a search covers its first 50 Ads.
- The TikTok Ad Library covers Ads shown in the EU/EEA, the UK, Switzerland and Turkey only.
Commercial Ads outside the EU, from our API
A real search on our own account, trimmed to three of the 50 Ads it returned. These are US commercial Ads for budgeting apps, the kind the official API leaves out unless they also reached the EU. The reach block is null because Meta discloses no spend for commercial Ads.
Meta Ad Library, via REST API
POST /v1/ads/search { "library": "meta", "query": "budgeting app", "country": "US", "status": "all", "order_by": "winner", "limit": 50 }
{
"run": { "kind": "ads_search", "status": "completed", "charge_credits": 50 },
"result": {
"library": "meta",
"items": [
{
"kind": "commercial",
"advertiser": { "name": "PadSplit" },
"creative": { "title": "First Booking? Get $100 Off", "cta": "Install now", "format": "VIDEO" },
"placements": ["FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER", "THREADS"],
"first_shown": "2026-06-26",
"days_running": 128,
"is_active": true,
"reach": { "spend": null, "impressions": null, "audience": null, "currency": null },
"winner_score": { "score": 100, "confidence": "low", "reason": "single_snapshot" }
},
{
"kind": "commercial",
"advertiser": { "name": "Quicken" },
"creative": { "cta": "Learn more" },
"media_type": "image",
"placements": ["FACEBOOK", "INSTAGRAM", "MESSENGER", "WHATSAPP", "THREADS"],
"first_shown": "2026-07-27",
"days_running": 97,
"is_active": true,
"reach": { "spend": null, "impressions": null, "audience": null, "currency": null }
},
{
"kind": "commercial",
"advertiser": { "name": "Budget by Steph" },
"media_type": "video",
"first_shown": "2025-11-08",
"last_shown": "2026-05-25",
"days_running": 197,
"is_active": false,
"variant_count": 2,
"reach": { "spend": null, "impressions": null, "audience": null, "currency": null }
}
],
"next_cursor": "..."
}
}
(50 Ads returned; 3 shown, with ids, copy, media URLs and some fields trimmed)The official API and ShortsIntel side by side
| Question | Meta Ad Library API | ShortsIntel |
|---|---|---|
| Commercial Ads outside the EU | Not returned. | Returned for any country the public Ad Library covers. |
| Setup | Identity confirmation, developer account, app and access token. | One API key, or connect your Assistant over MCP and sign in. |
| Spend for commercial Ads | Not disclosed. | Not disclosed. Ranked by days running and variants instead. |
| Sorting | The library's order. | Relevance, winner Score, days running or start date. |
| Analysis of the creative | None. | Hook, call to action, offer, format and transcript per Ad, on request. |
| Cost | Free. | 1 credit per Ad delivered. |
What it costs
There is no subscription. Each search is a Run, paid from a prepaid Balance of Credits at 1,000 credits per US dollar. New accounts get 1,000 credits free, valid for 90 days. A Run that fails costs nothing, and a partial one is charged only for what finished.
A Meta Ad search costs 1 credit per Ad delivered, and 20 credits more per Ad you ask to have analysed. One Ad by its library id is 3 credits, and an Advertiser lookup 15 credits. Reading an Ad's stored analysis and its snapshots is free. Every paid call can quote its price first. The full list is on the pricing page.
Search Meta Ads from your Assistant
Over MCP the same search is the search_ads tool. The server address is https://www.shortsintel.com/api/mcp, the same for every Assistant, and none of them needs an API key.
Claude.ai
Web and desktop. No API key: Claude signs in to ShortsIntel for you.
- Open Claude's add connector page with ShortsIntel filled in, and choose Add. Or go to Settings, Connectors, Add custom connector, and paste the endpoint below.
https://www.shortsintel.com/api/mcp - Sign in to ShortsIntel, approve the connection and choose the organization whose Balance pays for Runs.
- In a chat, turn the ShortsIntel connector on and ask your question.
ChatGPT
Web and desktop, in Developer mode. No API key: ChatGPT signs in over OAuth.
- Open ChatGPT's connector settings and switch Developer mode on.
- Create a connector named ShortsIntel, paste the endpoint and choose OAuth.
https://www.shortsintel.com/api/mcp - Sign in to ShortsIntel and choose your organization.
- In a new chat, choose the + next to the message box, then Developer mode, and turn ShortsIntel on.
Claude Code
One command, then sign in from Claude Code.
- Add the server in your terminal.
claude mcp add --transport http --scope user shortsintel https://www.shortsintel.com/api/mcp - Run /mcp inside Claude Code, choose shortsintel and sign in.
Codex
One command; Codex signs in on first use.
- Add the server in your terminal.
codex mcp add shortsintel --url https://www.shortsintel.com/api/mcp - If no browser window opens to sign in, start it yourself.
codex mcp login shortsintel
Cursor and VS Code
One-click install links; each asks you to confirm.
- In Cursor, open the Cursor install link.
- In VS Code, open the VS Code install link.
- Sign in to ShortsIntel when the editor asks.
Go deeper
- Competitor ad researchHow to pull a competitor's Meta and TikTok Ads into your Assistant, read which ones last, and turn them into a brief.
- Meta Ads MCPWhat an Assistant can do with the Meta Ad Library through the ShortsIntel MCP server: Ad and Advertiser search, Ad analysis, Snapshots and Advertiser Trackers.
- API referenceEvery /v1 operation, its parameters and its price.
Questions
- Does the Meta Ad Library API return commercial Ads?
- Only commercial Ads that reached someone in the EU. Outside the EU it returns only Ads about social issues, elections or politics, as of Graph API v26.0 in November 2026.
- Is the Facebook Ad Library API the same as the Meta Ad Library API?
- Yes. It is the same API, the ads_archive endpoint of Meta's Graph API. It covers Ads on Facebook, Instagram, Messenger and Meta's other placements.
- Does the Ad Library API show ad spend?
- Only for Ads about social issues, elections or politics, and then as ranges. Commercial Ads have no spend or impressions, and EU commercial Ads add EU reach instead.
- Do I need identity verification to use the Ad Library API?
- Yes. Meta asks you to confirm your identity and location at facebook.com/ID, which can take a few days, and then to create a developer account and an app.
- Is the Meta Ad Library API free?
- Yes, within Meta's rate limits. You still need identity confirmation and a developer app, and it does not return commercial Ads that ran only outside the EU.
- How do I get US commercial Ads from the Meta Ad Library?
- Meta's public Ad Library website shows them, but the official API does not. ShortsIntel reads the public library and returns those Ads as structured data over REST or MCP, with days running, status, variants and a winner Score.
Try it in your Assistant
Connect ShortsIntel to the Assistant you already use and ask the question this guide answers, or try the calls in the Playground first.