META AD LIBRARY API

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
Terminal
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"
}'
[ REQUEST AND RESPONSE ]

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

200 OK · application/json
{
"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
}
]
}
}
}
[ USE CASES ]

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.

[ FAQ ]

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.

Try the Meta Ad Details API

100 free credits on business email, no card. Your first call takes a minute.

APIMCPSDKCLI
free credits

On business email signup. No credit card required.

Start free with 100 credits