Facebook Ad Details API
Get everything the Meta Ad Library knows about one ad with a single request: the creatives and copy, the advertiser’s page profile, who paid for it and who benefits, and the transparency data that the EU Digital Services Act makes public.
For ads delivered in the European Union you get the total reach, the age range and gender of the audience, the targeted locations and a breakdown of reach by country, age and gender, as structured JSON.
No credit card needed. One API key works on every endpoint.
Quick example
https://api.scrapeadlibrary.com/v1/ads/{ad_id}curl "https://api.scrapeadlibrary.com/v1/ads/1550534860016399?country=IT" \
-H "X-API-Key: sal_your_api_key"{
"data": {
"id": "1550534860016399",
...every field of the Ad object...,
"advertiser": { ...Page object... },
"payers": [ { "payer": "Company Ltd", "beneficiary": "Company Ltd" } ],
"transparency": {
"eu": {
"reach": 65104,
"gender": "all",
"age_min": 21,
"age_max": 65,
"locations": [ { "name": "Italy", "type": "country", "excluded": false } ],
"breakdown": [
{ "country": "IT", "age_range": "18-24", "male": 31, "female": 1, "unknown": 0 }
]
},
"uk": null
},
"about": "Page about text",
"removed": false
},
"credits_used": 2,
"cached": false,
"media_expires_at": "2026-11-25T18:00:00Z"
}Illustrative values: a real response carries the live data of the ads and advertisers you ask for.
Fields on top of the Ad object
The response contains every field of an ad in the search results (creatives, copy, dates, platforms, political spend), plus:
| Field | Type | Description |
|---|---|---|
| advertiser | object | The page profile: category, likes, Instagram account, verification. |
| payers | array | Payer and beneficiary declared for the ad (persons pseudonymised). |
| transparency.eu | object | null | reach, gender, age_min, age_max, locations and breakdown of EU ads. |
| transparency.uk | object | null | The same data for ads delivered in the United Kingdom. |
| transparency.*.breakdown | array | Reach by country and age range, split into male, female and unknown. |
| about | string | null | The advertiser’s “about” text. |
| removed | boolean | True when Meta took the ad down for breaking its rules. |
Parameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
| ad_id | path | digits | required | The Ad Library ID of the ad. |
| country | query | string | ALL | ISO 3166 alpha-2 country code or ALL: the country whose view of the ad you want |
What people build with it
Audience insights
See which ages, genders and countries a competitor’s ad actually reached in the EU, not only who it targeted.
Compliance and brand safety
Check who paid for an ad that uses your brand, and archive the evidence with dates and creatives.
Ad performance proxies
Use EU reach and how long an ad kept running to rank which creatives of a competitor really worked.
Political transparency
Combine payer, beneficiary and spend ranges to follow who finances political and issue campaigns.
Pricing
One ad with all its details costs 2 credits. Not found and error responses are free.
- 100 free credits every month, no credit card
- Then $1 per 1,000 credits, pay as you go
- Only successful calls are billed: errors cost nothing
- Credits never expire; bulk packs from 10,000 credits for $9
Also in the MCP server for AI assistants
The ScrapeAdLibrary MCP server gives Claude, Cursor and other MCP clients the same data as tools: get_ad. Paste an Ad Library link into a chat and ask who the ad reached: the assistant reads the EU transparency data for you.
Run it with uvx scrapeadlibrary-mcp and your API key in SCRAPEADLIBRARY_API_KEY; the MCP server guide has the configuration for each client. Tool calls are billed like API calls.
Facebook Ad Details API: FAQ
- What does the ad details endpoint add to a search result?
- The advertiser’s full page profile, who paid for the ad and who benefits from it, and for ads delivered in the EU or the UK the transparency data: total reach, age range, gender, targeted locations and reach by country, age and gender.
- Where do I find the ad ID?
- In the id field of every search result, or at the end of an Ad Library link: facebook.com/ads/library/?id=<ad id>.
- Why is the transparency block null for some ads?
- Meta publishes reach and audience data under the Digital Services Act only for ads delivered in the European Union (and the UK’s equivalent for UK ads). For ads shown only elsewhere, eu and uk are null.
- Are private persons’ names returned?
- No. When the advertiser is a person profile its picture is never returned, and payer or beneficiary names that look like natural persons are replaced by a pseudonym of the form person:<hash>, as our privacy policy explains.
- How much does one ad cost?
- 2 credits per ad. An ad that does not exist answers 404 ad_not_found and costs nothing.
Related APIs
- Facebook Ads Search APISearch the Ad Library by keyword or advertiser, with country, platform, media and date filters.
- Facebook Page Ads APIThe profile of an advertiser page and every ad it runs, page by page.
- Facebook Advertiser Search APIFind the advertisers that ran ads on a keyword, with their page ID and category.
- Free Ad Library searchTry the data in the browser: a few free searches a day, no account.
Every parameter and error code is in the ad detail reference.
Look inside any ad of the Ad Library
Create a free account and call the endpoint with any ad ID. 100 free credits every month.