META AD LIBRARY API

Meta Ad Library API

Search ads running on Facebook, Instagram and Meta’s other apps by keyword or advertiser, with filters for country, active status, ad category, media type, platform, language and dates. Each ad includes its text, images, videos, carousel cards, link, call to action, run dates, platforms and advertiser, plus spend, impressions and the paid-for-by disclaimer for ads about social issues, elections or politics.

Endpoint
POST /meta-ads/search
Price
1 credit per result
SDK
client.metaAds.search()
MCP tool
meta_ads_search
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
}'
[ REQUEST AND RESPONSE ]

What does the Meta Ad Library API return?

Meta Ad Library API: search ads running on Facebook and Instagram by keyword, advertiser, country, status and media type, as structured JSON. Every response has the same envelope: the result in data, plus timeMs and the creditsCost of the call.

Request body

qstring
Keywords to search the ads’ text for, e.g. "running shoes". Leave it out to list every ad matching the other filters.
pageIdstring
Only return ads from this advertiser: its Facebook Page ID, 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.
exactPhraseboolean · default false
Match `q` as an exact phrase instead of matching any ad that has all its words. Defaults to false.
countrystring · default ALL
Two-letter country code to search ads shown in, e.g. "US" or "GB", or "ALL" for every country. Defaults to "ALL".
activeStatusenum · default active
Return ads that are still running ("active"), that stopped ("inactive"), or both ("all"). Defaults to "active".
active | inactive | all
adTypeenum · default all
Ad category: "all", "political_and_issue_ads" (social issues, elections or politics), "housing_ads", "employment_ads" or "credit_ads". Defaults to "all".
all | political_and_issue_ads | housing_ads | employment_ads | credit_ads
mediaTypeenum · default all
Media in the ad: "all", "image", "meme", "image_and_meme", "video", or "none" for ads with no image or video. Defaults to "all".
all | image | meme | image_and_meme | video | none
platformsenum[]
Only return ads running on these platforms, e.g. ["instagram"]. Leave it out for every platform.
languagesstring[]
Only return ads in these languages, as two-letter codes, e.g. ["en", "es"].
startDatestring
Only return ads that ran on or after this date (YYYY-MM-DD), e.g. "2026-01-01".
endDatestring
Only return ads that ran on or before this date (YYYY-MM-DD), e.g. "2026-03-31".
sortByenum · default impressions
Order of the ads: most seen first ("impressions"), or recently started ads first ("recent"), which Meta orders roughly rather than strictly by start date. Defaults to "impressions".
impressions | recent
countinteger · 1–30 · default 10
Number of results to return (1–30). Defaults to 10.
cursorstring
The previous response's `nextCursor`, to fetch the next page. Omit it for the first page.
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": {
"nextCursor": "string",
"ads": [
{
"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
}
]
}
}
[ USE CASES ]

What can you build with the Meta Ad Library API?

Research competitors

See which ads competitors are running right now.

Find creative ideas

Collect ads in your category to study hooks and formats.

Track ad activity

Watch when advertisers start and stop campaigns.

[ FAQ ]

Meta Ad Library API questions

How do I search the Facebook Ad Library with an API?

Send a keyword or an advertiser’s Page ID together with the country, status and media type you want. The matching ads come back as structured JSON, with their text, images, videos, links and run dates.

Can I see which ads a competitor is running?

Yes. Find the competitor’s Page ID with the advertiser search, then search with that Page ID and limit the results to active ads to see what they are running right now.

Can I page through more ads?

Yes. Each response has a nextCursor; send it back as cursor to get the next page, until it is null.

How do I use the Meta Ad Library API?

Send a POST request to https://api.bridgly.app/meta-ads/search with the filters you want in the JSON body and your API key in the Authorization header. In the TypeScript SDK, call client.metaAds.search(). AI agents connected to Bridgly over MCP can call the meta_ads_search tool.

How much does the Meta Ad Library API cost?

Costs 1 credit per result returned, with a minimum of 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 Library 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