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
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}'import osimport requestsresponse = requests.post( "https://api.bridgly.app/meta-ads/search", headers={"Authorization": f"Bearer {os.environ['BRIDGLY_KEY']}"}, json={ "q": "running shoes", "country": "US", "count": 10, },)data = response.json()const response = await fetch("https://api.bridgly.app/meta-ads/search", { method: "POST", headers: { Authorization: `Bearer ${process.env.BRIDGLY_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "q": "running shoes", "country": "US", "count": 10 }),});const data = await response.json();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);}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
{ "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 } ] }}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.
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 it with a free tool
Look up a public example in your browser before connecting the API. No account needed.
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 Details API→Meta Ad Library details API: get one Facebook or Instagram ad by its Library ID, with creative, run dates, payer, reach and audience demographics.
Try the Meta Ad Library API
100 free credits on business email, no card. Your first call takes a minute.