Meta Ad Details API
Get one ad from the Meta Ad Library by its Library ID or link: its creative, run dates, platforms and advertiser, who paid for it and who it benefits, and where Meta publishes them, its targeting, reach by country, age and gender, and the audience of ads about social issues, elections or politics.
- Endpoint
- POST /meta-ads/get-ad-details
- Price
- 1 credit per request
- SDK
- client.metaAds.getAdDetails()
- MCP tool
- meta_ads_get_ad_details
curl -X POST "https://api.bridgly.app/meta-ads/get-ad-details" \ -H "Authorization: Bearer $BRIDGLY_KEY" \ -H "Content-Type: application/json" \ -d '{ "adId": "1806650610330561"}'import osimport requestsresponse = requests.post( "https://api.bridgly.app/meta-ads/get-ad-details", headers={"Authorization": f"Bearer {os.environ['BRIDGLY_KEY']}"}, json={ "adId": "1806650610330561", },)data = response.json()const response = await fetch("https://api.bridgly.app/meta-ads/get-ad-details", { method: "POST", headers: { Authorization: `Bearer ${process.env.BRIDGLY_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "adId": "1806650610330561" }),});const data = await response.json();import { Bridgly } from "@bridgly/sdk";const client = new Bridgly({ apiKey: "bgly_YOUR_KEY" });const res = await client.metaAds.getAdDetails({ adId: "1806650610330561"});if (res.type === "success") { console.log(res.data);}What does the Meta Ad Details API return?
Meta Ad Library details API: get one Facebook or Instagram ad by its Library ID, with creative, run dates, payer, reach and audience demographics. Every response has the same envelope: the result in data, plus timeMs and the creditsCost of the call.
Request body
adIdstringrequired- Ad Library ID of the ad, or its Ad Library link, e.g. "1806650610330561" or "https://www.facebook.com/ads/library/?id=1806650610330561".
cacheMaxAgeHoursinteger- Accept a cached result scraped up to this many hours ago. A cached result costs no credits, and its `cachedAt` says when it was scraped. When no cached result is that recent, the data is scraped live at the normal price. Leave it out to always scrape live, e.g. 24.
cacheOnlyboolean- Return only a cached result and never scrape live. With `cacheMaxAgeHours`, only a result that recent is returned; without it, the latest cached result of any age. Responds 404, at no cost, when there is none, e.g. true.
Example response
{ "timeMs": 1840, "creditsCost": 1, "cachedAt": "2026-01-15T09:30:00.000Z", "data": { "id": "string", "url": "string", "isActive": true, "startDate": "string", "endDate": "string", "page": { "id": "string", "name": "string", "url": "string", "profilePictureUrl": "string", "likes": 0, "categories": [ "string" ], "isDeleted": true }, "partnerPage": { "id": "string", "name": "string", "url": "string" }, "paidForBy": "string", "displayFormat": "string", "title": "string", "body": "string", "caption": "string", "linkUrl": "string", "linkDescription": "string", "ctaText": "string", "ctaType": "string", "images": [ "string" ], "videos": [ { "hdUrl": "string", "sdUrl": "string", "previewImageUrl": "string" } ], "cards": [ { "title": "string", "body": "string", "caption": "string", "linkUrl": "string", "linkDescription": "string", "ctaText": "string", "ctaType": "string", "imageUrl": "string", "video": { "hdUrl": "string", "sdUrl": "string", "previewImageUrl": "string" } } ], "textVariations": [ "string" ], "linkVariations": [ "string" ], "platforms": [ "string" ], "categories": [ "string" ], "collationId": "string", "collationCount": 0, "targetedCountries": [ "string" ], "impressions": "string", "spend": "string", "currency": "string", "reachEstimate": "string", "disclaimer": { "verification": "string", "submittedOn": "string", "phone": "string", "email": "string", "website": "string", "address": "string" }, "stateMediaLabel": "string", "containsDigitallyCreatedMedia": true, "advertiser": { "id": "string", "name": "string", "username": "string", "url": "string", "profilePictureUrl": "string", "likes": 0, "category": "string", "isVerified": true, "instagramUsername": "string", "instagramFollowers": 0, "instagramVerified": true, "isDeleted": true }, "payer": { "name": "string", "website": "string", "location": "string" }, "beneficiary": { "name": "string", "website": "string", "location": "string" }, "targeting": { "locations": [ { "name": "string", "type": "string", "excluded": true } ], "gender": "string", "ageMin": 0, "ageMax": 0 }, "totalReach": 0, "reachBreakdown": [ { "country": "string", "ageRange": "string", "gender": "string", "reach": 0 } ], "audience": { "country": "string", "byAgeAndGender": [ { "ageRange": "string", "gender": "string", "share": 0 } ], "byRegion": [ { "region": "string", "share": 0 } ] } }}What can you build with the Meta Ad Details API?
Study a campaign
Read an ad’s creative, run dates and reach in one call.
Understand audiences
See the ages, genders and places an ad reached.
Archive ads
Save the details of ads you report on.
Meta Ad Details API questions
How do I get the details of one Facebook ad?
Send the ad’s Library ID or its Ad Library link. You get its creative, run dates and advertiser and, where Meta publishes them, who paid for it, its targeting, its reach and its audience by age and gender.
Which ads have reach and demographics?
Meta publishes reach, targeting and an age and gender breakdown for ads shown in the EU, the UK and Brazil, and audience shares for ads about social issues, elections or politics. Other ads come back with their creative and advertiser only.
How do I use the Meta Ad Details API?
Send a POST request to https://api.bridgly.app/meta-ads/get-ad-details with adId in the JSON body and your API key in the Authorization header. In the TypeScript SDK, call client.metaAds.getAdDetails(). AI agents connected to Bridgly over MCP can call the meta_ads_get_ad_details tool.
How much does the Meta Ad Details API cost?
Costs 1 credit per request. Credits cost $2.00 per 1,000 on pay-as-you-go and as low as $1.67 per 1,000 at volume. New accounts on a business email start with 100 free credits, and failed requests are never charged.
More Meta Ad Library endpoints
The same API key works on every endpoint. See all Meta Ad Library API endpoints.
- Meta Ad Library Advertiser Search API→Find advertisers in the Meta Ad Library by brand name and get their Page ID, category, likes, verification and Instagram account as JSON.
- Meta Ad Library Advertiser API→Get a Meta Ad Library advertiser by Page ID: page, Instagram account, ad count, confirmed owner, page history and political ad spend as JSON.
- Meta Ad Library API→Meta Ad Library API: search ads running on Facebook and Instagram by keyword, advertiser, country, status and media type, as structured JSON.
Try the Meta Ad Details API
100 free credits on business email, no card. Your first call takes a minute.