META AD LIBRARY API

Meta Ad Library API for Facebook and Instagram ads

Search every ad in the Meta Ad Library by keyword or advertiser, then pull an ad’s creative, reach and targeting or an advertiser’s owner and political spend, all as JSON.

request.ts
import { Bridgly } from "@bridgly/sdk";
const client = new Bridgly({ apiKey: "bgly_YOUR_KEY" });
const res = await client.metaAds.search({
q: "running shoes",
country: "US",
count: 10
});
if (res.type === "success") {
console.log(res.data);
}

npm install @bridgly/sdk

[ ENDPOINTS ]

All 4 Meta Ad Library endpoints

Ad search covers every ad in the Meta Ad Library, not only political ones. Search by keyword or exact phrase, or list one advertiser’s ads by Page ID, and filter by country, active status, ad category, media type, platform, language and dates. Each ad comes with its text, headline, images, videos, carousel cards, link, call to action, run dates, platforms and advertiser page, and results page with a cursor.

Ad details adds what the Ad Library shows when you open one ad: the advertiser’s page and Instagram account, who paid for the ad and who it benefits, and, for ads shown in the EU, the UK or Brazil, its targeting and the people it reached by country, age and gender. Ads about social issues, elections or politics also carry spend, impressions and the share of their audience by age, gender and region.

Advertiser search finds a brand’s pages by name and returns the Page IDs the other endpoints take. Advertiser details returns the page, its About text and ad count, the organization Meta confirmed owns it, its name history, the countries its managers are in, and for political advertisers their spend and targeting over the last 30 days.

Meta Ad Details API

POST/meta-ads/get-ad-details
Meta Ad Library details API: get one Facebook or Instagram ad by its Library ID, with creative, run dates, payer, reach and audience demographics.1 credit per requestDetails →
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.
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
}
]
}
}
}

Meta Ad Library Advertiser Search API

POST/meta-ads/search-companies
Find advertisers in the Meta Ad Library by brand name and get their Page ID, category, likes, verification and Instagram account as JSON.1 credit per requestDetails →
Request body
qstringrequired
Name of the brand or advertiser to look for, e.g. "nike".
countrystring · default ALL
Two-letter country code to favor advertisers from, e.g. "US", or "ALL". Defaults to "ALL".
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.
Response
200 OK · application/json
{
"timeMs": 1840,
"creditsCost": 1,
"cachedAt": "2026-01-15T09:30:00.000Z",
"data": {
"companies": [
{
"id": "string",
"name": "string",
"username": "string",
"profilePictureUrl": "string",
"likes": 0,
"category": "string",
"isVerified": true,
"instagramUsername": "string",
"instagramFollowers": 0,
"instagramVerified": true,
"isDeleted": true,
"country": "string"
}
]
}
}

Meta Ad Library Advertiser API

POST/meta-ads/get-company
Get a Meta Ad Library advertiser by Page ID: page, Instagram account, ad count, confirmed owner, page history and political ad spend as JSON.1 credit per requestDetails →
Request body
pageIdstringrequired
Facebook Page ID of the advertiser, e.g. "15087023444", as returned in `page.id` or by the advertiser search. The Ad Library link of the advertiser’s ads (`?view_all_page_id=<id>`) works too.
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.
Response
200 OK · application/json
{
"timeMs": 1840,
"creditsCost": 1,
"cachedAt": "2026-01-15T09:30:00.000Z",
"data": {
"id": "string",
"name": "string",
"username": "string",
"url": "string",
"profilePictureUrl": "string",
"likes": 0,
"category": "string",
"isVerified": true,
"instagramUsername": "string",
"instagramFollowers": 0,
"instagramVerified": true,
"isDeleted": true,
"about": "string",
"adCount": 0,
"owner": {
"name": "string",
"phone": "string",
"city": "string",
"state": "string",
"postalCode": "string",
"country": "string"
},
"history": [
{
"type": "string",
"date": "string"
}
],
"adminCountries": [
{
"country": "string",
"count": 0
}
],
"politicalAds": {
"periodEnd": "string",
"adCount": 0,
"totalSpend": "string",
"currency": "string",
"targeting": [
{
"dimension": "string",
"value": "string",
"type": "string",
"excluded": true,
"adCount": 0,
"spendShare": 0
}
]
}
}
}
[ WHY NOT THE OFFICIAL API? ]

Why not the official Meta Ad Library API?

Meta’s own Ad Library API returns ads about social issues, elections or politics, plus ads shown in the EU, and only after you confirm your identity and set up a Meta developer app.

Every ad, not only political ones

Search commercial ads in any country, with the same filters as the Ad Library website.

The creative itself

Get the ad’s text, image and video files, carousel cards, link and call to action, instead of a link to a snapshot page.

No identity check or app review

There is no ID confirmation, developer app or access token to manage. One Bridgly key covers Meta ads and every other platform.

[ HOW TO USE IT ]

Your first Meta Ad Library call

Terminal
curl -X POST "https://api.bridgly.app/meta-ads/search" \
-H "Authorization: Bearer $BRIDGLY_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "running shoes",
"country": "US",
"count": 10
}'
[ USE CASES ]

What people build with Meta Ad Library data

Watch competitors’ ads

Find a competitor’s Page ID with the advertiser search, then list the ads it is running right now and see when each started.

Collect creative inspiration

Search a product category, sort by impressions, and pull the copy, images and videos of the ads that run longest.

Research political advertising

Get spend, impressions, audience shares and paid-for-by disclaimers for ads about social issues, elections or politics.

Vet an advertiser

See the organization behind a page, when it was created or renamed, and which countries it is managed from.

[ LIMITS ]

What the Meta Ad Library API does not do

  • Ad search returns up to 30 ads per call; page through the rest with the cursor.
  • Advertiser search returns up to 15 advertisers per name and is not paginated.
  • Spend, impressions and audience shares are published only for ads about social issues, elections or politics.
  • Targeting and reach by country, age and gender are published only for ads shown in the EU, the UK or Brazil.
  • Sorting by "recent" puts recently started ads first, but Meta does not order them strictly by start date.
[ FAQ ]

Meta Ad Library API questions

Does it cover ads that are not political?

Yes. Ad search covers every ad in the Meta Ad Library, from any advertiser and country. Spend and impressions are only published for ads about social issues, elections or politics.

How do I see all the ads of one company?

Search the brand’s name with the advertiser search to get its Page ID, then send that Page ID to ad search. Set activeStatus to "all" to include ads that stopped running.

Do I get the images and videos of each ad?

Yes. Each ad includes its image and video file links, with the cards of carousel and catalog ads, alongside the text, link and call to action.

Do I need a Meta developer account?

No. You authenticate with your Bridgly API key only. There is no identity confirmation, developer app or access token to set up.

How much does it cost?

Ad search costs one credit per ad returned. Ad details, advertiser search and advertiser details cost one credit per call. What a credit costs in dollars depends on your pricing package, and goes as low as $1.67 per 1,000 credits at volume.

Start pulling Meta Ad Library data

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