How to run a Facebook Ad Library search
GET request to /v1/ad-library/facebook/search with your input. You get clean JSON back in seconds for 2 credits per call — no OAuth, scraping or platform SDKs. Search Meta Ad Library by keyword — active/inactive, media type, date range, platforms, cursor, and spend/impressions when Meta publishes them.How to run a Facebook Ad Library search (step by step)
- 1
Get a free API key
Create a free Captapi account (100 credits, no card) and generate an API key from the dashboard.
- 2
Call the Facebook Ad Library Search API
Send an authenticated GET request to /v1/ad-library/facebook/search with your input. No OAuth, no scraping setup.
- 3
Read the JSON response
Parse the clean JSON response. Pass cache=true for a free 24h cache hit; default is always fresh.
Code example
curl "https://api.captapi.com/v1/ad-library/facebook/search?q=election" \
-H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."What the response looks like
{
"success": true,
"data": {
"query": "election",
"country": "US",
"totalReturned": 2,
"ads": [
{
"platform": "facebook_ad_library",
"id": "317161109571794",
"url": "https://www.facebook.com/ads/library/?id=317161109571794",
"text": "The Voting Information Center—one-tap voting registration information from election experts and authorities in one place.",
"headline": "Voting Information Center",
"cta": "Learn more",
"landingUrl": "http://facebook.com/votinginformationcenter",
"adFormat": "VIDEO",
"firstShown": "2020-09-22T07:00:00.000Z",
"lastShown": "2020-10-05T07:00:00.000Z",
"impressions": ">1M",
"spend": ">$1M",
"country": "US",
"advertiser": {
"id": "108824017345866",
"name": "Meta",
"url": "https://www.facebook.com/Meta/",
"logo": "https://scontent-atl3-1.xx.fbcdn.net/v/t1.6435-9/119568341_200337161527884_7846459746434232698_n.png?stp=dst-png_s60x60&_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=qaRlosGC9wUQ7kNvwHuGOSN&_nc_oc=AdpUTiQHP0F2DQWlJJsFhLjPwiKgiTaMBS9Gf3J_Ogy1Z6nYv2kt_BhKXvw8jPupOMg&_nc_zt=23&_nc_ht=scontent-atl3-1.xx&_nc_gid=kjSzmNhJvOQPmxnVKKr0xg&_nc_ss=72289&oh=00_AQCbS0Qc_-2kHNJh8Yysq78dbBXaaJS4Osw3-xA3_SHVlw&oe=6A89438E"
},
"media": [
"https://video-atl3-1.xx.fbcdn.net/o1/v/t2/f2/m412/AQNN757NtitUcJnpv0ODeMH6fXo-yFM-X90P2W82Zsrc70oOzST9lrKgscKf21SHBUtZ9pdKMclY8s32B0eRJ7o.mp4?_nc_cat=106&_nc_sid=ef5aa3&_nc_ht=video-atl3-1.xx.fbcdn.net&_nc_ohc=VIhm6QH6QpYQ7kNvwEGz32Z&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuMzQwLmFzaWNfaHExX3NkX3Byb2dyZXNzaXZlIiwieHB2X2Fzc2V0X2lkIjo4MzE0MTAwMzMxNDk2MzYsImFzc2V0X2FnZV9kYXlzIjoyMzcsInZpX3VzZWNhc2VfaWQiOjEwNjgwLCJkdXJhdGlvbl9zIjoxNSwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_gid=kjSzmNhJvOQPmxnVKKr0xg&_nc_ss=72289&_nc_zt=28&oh=00_AQBmg1RWfbVvJ3MUBSfprUeNw4A1j1otLN5iP3DoZ8RxIw&oe=6A677448",
"https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/120065387_2711663819108220_8472417301728012411_n.jpg?_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=XJsOGtccv7UQ7kNvwFOmuvH&_nc_oc=AdqJh0Avn_pYIk_hzhEW3QS1dyOrrTJn4nBpQ38NLoUvb1OE8Kwj7qy75S7f1QbV1cs&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=kjSzmNhJvOQPmxnVKKr0xg&_nc_ss=72289&oh=00_AQBESYOW184a4FJWDENcSYwQSBzwkH5yonZh3U5v6ZZEgA&oe=6A67964A"
]
},
{
"platform": "facebook_ad_library",
"id": "372804137235499",
"url": "https://www.facebook.com/ads/library/?id=372804137235499",
"text": "The Voting Information Center on Facebook—one-tap voting info from election experts and authorities in one place.",
"headline": "Voting Information Center",
"cta": "Learn more",
"landingUrl": "http://facebook.com/votinginformationcenter",
"adFormat": "VIDEO",
"firstShown": "2020-10-05T07:00:00.000Z",
"lastShown": "2020-10-13T07:00:00.000Z",
"impressions": ">1M",
"spend": ">$1M",
"country": "US",
"advertiser": {
"id": "108824017345866",
"name": "Meta",
"url": "https://www.facebook.com/Meta/",
"logo": "https://scontent-atl3-1.xx.fbcdn.net/v/t1.6435-9/119568341_200337161527884_7846459746434232698_n.png?stp=dst-png_s60x60&_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=qaRlosGC9wUQ7kNvwHuGOSN&_nc_oc=AdpUTiQHP0F2DQWlJJsFhLjPwiKgiTaMBS9Gf3J_Ogy1Z6nYv2kt_BhKXvw8jPupOMg&_nc_zt=23&_nc_ht=scontent-atl3-1.xx&_nc_gid=kjSzmNhJvOQPmxnVKKr0xg&_nc_ss=72289&oh=00_AQCbS0Qc_-2kHNJh8Yysq78dbBXaaJS4Osw3-xA3_SHVlw&oe=6A89438E"
},
"media": [
"https://video-atl3-1.xx.fbcdn.net/o1/v/t2/f2/m412/AQPYrtdWcXYzwK9kZxgDiAgoU_IImyeS9Q8adbGcircR7RR1dDdUBrAQ0LiHO2OJoauE5pf8F4GyEcPVDLQ94uo.mp4?_nc_cat=100&_nc_sid=ef5aa3&_nc_ht=video-atl3-1.xx.fbcdn.net&_nc_ohc=TJVBi21FSYoQ7kNvwGc3J8g&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuMzQwLmFzaWNfaHExX3NkX3Byb2dyZXNzaXZlIiwieHB2X2Fzc2V0X2lkIjo4OTE2MjkwMDA0NTQwNDEsImFzc2V0X2FnZV9kYXlzIjoxNTcsInZpX3VzZWNhc2VfaWQiOjEwNjgwLCJkdXJhdGlvbl9zIjoxNCwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_gid=kjSzmNhJvOQPmxnVKKr0xg&_nc_ss=72289&_nc_zt=28&oh=00_AQCMG2KnWhkyJxkleqImsnYBBqDKo2-gU04sjFZY6UOemA&oe=6A678682",
"https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/120439450_1980569842077757_2547343747583380554_n.jpg?_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=ghBwQrPN7IYQ7kNvwEK1Ioe&_nc_oc=Adq-eL0xdnXQzWG8i4nmzYYnwcV_Aa55yUcMBwzE5_rk0sejWdtPX_5QJKW6xounlWk&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=kjSzmNhJvOQPmxnVKKr0xg&_nc_ss=72289&oh=00_AQB1w19aEluVfs5pAiHsky2u5dZ4bgAW_AohS8QzRc8Wkg&oe=6A678BF4"
]
}
]
}
}Billing metadata (credits charged, cache hit/miss) is returned in the X-Captapi-Credits and X-Captapi-Cache response headers.
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
| q | string | Yes | Keyword, brand, or advertiser to search Meta Ad Library (min 2 characters). |
| country | string | No | Two-letter ISO country code (e.g. US, GB, DE). Default US. |
| limit | integer | No | Max items to return (default 20, max 200). Flat 2 credits per call. |
| status | string | No | Ad delivery status: ACTIVE (default), INACTIVE, or ALL. Use ACTIVE for "what are they running now?". |
| media_type | string | No | Creative filter: ALL (default), IMAGE, VIDEO, MEME, IMAGE_AND_MEME, or NONE. |
| platforms | string | No | Comma-separated publisher platforms to keep: FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, THREADS. |
| ad_type | string | No | all (default) or political_and_issue_ads. Spend/impressions are typically only filled for political/issue ads. |
| search_type | string | No | keyword_unordered (default) or keyword_exact_phrase. |
| sort_by | string | No | Meta sort mode: total_impressions or relevancy_monthly_grouped. |
| start_date | string | No | Only ads with delivery start on/after this date (YYYY-MM-DD). |
| end_date | string | No | Only ads with delivery start on/before this date (YYYY-MM-DD). |
| cursor | string | No | Pagination cursor from a previous nextCursor. Pages through the current Meta HTML result batch. |
| trim | boolean | No | When true, omit cards/images/videos typed arrays (media[] stays). Captapi payloads are already lean vs Meta nested snapshots. |
| cache | boolean | No | Set true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh. |
Frequently asked questions
What does the Facebook Ad Library Search API do?
The Facebook Ad Library Search API lets you search and return matching results from a public Facebook Ad Library query using one GET request to /v1/ad-library/facebook/search. It returns clean JSON — no OAuth or infrastructure setup required.
How many credits does the Facebook Ad Library Search API cost?
Each successful call costs 2 credits. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Failed or empty results are never charged.
Do I need a Facebook Ad Library API key or OAuth?
No. A single Captapi key works across every platform Captapi supports — YouTube, TikTok, Instagram, Facebook, Twitter/X, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Rumble, Spotify, Kwai, and more. We handle proxies, rate limits, retries, and authentication for you.
How do I find current campaigns instead of 2020 ads?
Use status=ACTIVE (default) plus start_date (YYYY-MM-DD). For spend/impressions in most markets set ad_type=political_and_issue_ads — commercial ads usually return null spend. Page with nextCursor within the current HTML batch; refine the query when nextCursor is null.
Why is searchResultsCount much larger than retrievableCount?
searchResultsCount is Meta's claimed match total (it can move between calls). retrievableCount is how many ads this cursor walk can actually return — the fetched HTML batch, typically ~30–50. Walk nextCursor until hasMore is false; that is the ceiling, not the big number.
Why did I get two near-identical ads in a limit=3 page?
Those rows share collationId — Meta lists creative variants as separate ads (different id / firstShown / lastShown, same copy and media). Same advertiser id collapsing to one name is name normalisation, not dedup. Group on collationId if you want one row per creative; each sibling still consumes a limit slot. collationId is always keyed; null means Meta omitted it on the whole group (we copy a sibling's id within one collated_results array, we do not invent one).
Why is text "{{product.brand}}" — or why does it match cards[0]?
Dynamic Creative (adFormat=DCO) stores Handlebars tokens at the creative level. We fall back to cards[0] when that card has real copy and set textIsFromCard so you can tell card copy from the template. If the card is also a token, text stays templated and isTemplated is true.
Why are spend, impressions, reach, byline, and disclaimerLabel null on every row?
That is Meta's limit, not a scrape miss. Meta publishes spend, impressions, reach, and the paid-for-by extras only for political and issue ads in regions that require disclosure; commercial advertisers omit them. politicalCountries: [] on a row is the commercial signal. Set ad_type=political_and_issue_ads when you need those bands.
Which media array should I archive?
media[] is the canonical URL list (one primary asset per creative, including DCO cards). images[] / videos[] are the typed extras — they are now filled from cards when Meta leaves them empty. CDN links die in about five days; read mediaUrlsExpireAt (oe=) and refetch rather than cache.
Is the Facebook Ad Library Search API suitable for production use?
Yes. It is a stable REST endpoint with predictable JSON and automatic retries. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Use it for analytics, monitoring, and content automation.
Ready to run a Facebook Ad Library search?
Start free with 100 credits — no credit card required.
Get your free API key