CaptapiCaptapi
Facebook Ad Library
GET /v1/ad-library/facebook/search

Facebook Ad Library Search API

Search Meta Ad Library by keyword — active/inactive, media type, date range, platforms, cursor, and spend/impressions when Meta publishes them.

2 credits per request
Try in PlaygroundGet your API key — freeRead the docs
TL;DR
Search Meta Ad Library by keyword — active/inactive, media type, date range, platforms, cursor, and spend/impressions when Meta publishes them. The Facebook Ad Library Search API (Facebook Ad Library) is a single authenticated GET request to /v1/ad-library/facebook/search that responds with clean JSON and costs 2 credits. Pass cache=true for a free 24h cache hit; default is always fresh. Start with 100 free credits — no credit card.

What is the Facebook Ad Library Search API?

Search Meta's Ad Library and get competitor creatives as clean JSON — filters: status (default ACTIVE), media_type, platforms, ad_type, search_type (exact phrase), sort_by (total_impressions|relevancy_monthly_grouped), start_date/end_date, cursor, trim. Cursor pages the current HTML result batch via nextCursor (not Meta's multi-thousand POST cursor). hasMore is true only when nextCursor is present. searchResultsCount is Meta's upstream match count (can be thousands); retrievableCount is how many ads this cursor walk can actually return (the fetched HTML batch, typically ~30–50) — publish both; the big number is not walkable. Same advertiser id collapses to one name within a response (name normalisation, not dedup). Collation siblings share collationId and each consume a limit slot — group on that key if you want one row per creative; collationId is always keyed (null when Meta omits it) and siblings in one collated_results group inherit a missing id. Each ad: text/headline/cta/ctaType/landingUrl, media[] (canonical URL list) plus typed images/videos + cards[], isActive, publisherPlatforms (not a platforms twin), pageLikeCount/pageCategories/pageEntityType, politicalCountries, reachEstimate, spend/impressions when Meta publishes them. Meta publishes spend, impressions, reach, and the paid-for-by extras (byline, disclaimerLabel, brandedContent, pageEntityType, totalActiveTime) only for political and issue ads in regions that require disclosure; commercial advertisers omit them — politicalCountries: [] is the signal, not a scrape miss. DCO creatives substitute cards[0] when text/headline/linkDescription are {{product.*}} tokens and set textIsFromCard (leftover tokens keep isTemplated). images[]/videos[] are filled from cards when Meta leaves the typed arrays empty. mediaUrlsExpireAt is the earliest Meta CDN oe= stamp (~5 days). variantCount is always keyed (null when Meta omits it). advertiser is {id,name,url,logo,profileId?} — id is the Ad Library page id; profileId is the facebook.com/{digits} namespace when it differs; identical pageId/advertiserId aliases are not emitted. firstShown/lastShown are calendar days (YYYY-MM-DD) in Pacific — Meta's date, not an 8 a.m. UTC instant. Row-level country is omitted when Meta does not publish a per-ad market (the envelope country is the query). Envelope fetchMs / parseMs / totalMs survive the customer-trace strip so a ~13s call is attributable. Native fetch is capped at 110s. Flat 2 credits on the native path.

What you get

  • Ranked, structured result list
  • Title, URL, author, and thumbnail per result when available
  • Engagement metrics where the platform exposes them
  • Configurable result limit

Try it

Open in Playground

Fill in the parameters below and copy a ready-to-run request, or open the live Playground to run it against your account (no API key paste).

Parameters

Sign in to run live
curl "https://api.captapi.com/v1/ad-library/facebook/search?q=election" \
  -H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."

Edit the parameters and the code updates instantly. Switch languages and hit copy.

Example response

{
  "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 is returned in response headers: X-Captapi-Credits (credits charged), X-Captapi-Cache (hit or miss), and X-Captapi-Source. Failed requests (4xx/5xx) are never charged. See the full list of error codes in the error reference.

Response structure

A successful call returns success and a data object with the following fields:

Top-level fields

  • queryKeyword you searched.
  • countryISO market you queried (e.g. US, BD). Envelope only — not each ad's delivery country, and not a popular-creators feed market.
  • totalReturnedAds on this page (length of ads[]).

Ads

Each item in ads contains:

  • platformPlatform identifier for this response (matches the endpoint's platform).
  • idId of this ads item.
  • urlCanonical URL of the item.
  • textBody copy of the creative. DCO {{product.*}} tokens fall back to cards[0].text when that card has real copy.
  • headlineAd headline / title when Meta exposes it. Not a profile headline. DCO tokens fall back to cards[0] (see textIsFromCard).
  • ctaCall-to-action label (e.g. Learn more).
  • landingUrlClick-through URL from the creative.
  • adFormatCreative format Meta labelled (IMAGE, VIDEO, …).
  • firstShownMeta delivery-start date as YYYY-MM-DD (Pacific calendar day) — not an 8 a.m. UTC instant.
  • lastShownMeta delivery-end date as YYYY-MM-DD (Pacific calendar day) — not an 8 a.m. UTC instant.
  • impressionsImpression band when Meta publishes it. Commercial usually null — see platformNote.
  • spendSpend band when Meta publishes it (political/issue ads). Commercial usually null — see platformNote.
  • countryISO market you queried (e.g. US, BD). Envelope only — not each ad's delivery country, and not a popular-creators feed market.
  • advertiserAdvertiser running the ad.
  • mediaCanonical URL list — one primary asset per creative, including DCO cards. resizedUrl / posters live on images[] / videos[].

Parameters

NameTypeRequiredDescription
qstringYesKeyword, brand, or advertiser to search Meta Ad Library (min 2 characters).
countrystringNoTwo-letter ISO country code (e.g. US, GB, DE). Default US.
limitintegerNoMax items to return (default 20, max 200). Flat 2 credits per call.
statusstringNoAd delivery status: ACTIVE (default), INACTIVE, or ALL. Use ACTIVE for "what are they running now?".
media_typestringNoCreative filter: ALL (default), IMAGE, VIDEO, MEME, IMAGE_AND_MEME, or NONE.
platformsstringNoComma-separated publisher platforms to keep: FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, THREADS.
ad_typestringNoall (default) or political_and_issue_ads. Spend/impressions are typically only filled for political/issue ads.
search_typestringNokeyword_unordered (default) or keyword_exact_phrase.
sort_bystringNoMeta sort mode: total_impressions or relevancy_monthly_grouped.
start_datestringNoOnly ads with delivery start on/after this date (YYYY-MM-DD).
end_datestringNoOnly ads with delivery start on/before this date (YYYY-MM-DD).
cursorstringNoPagination cursor from a previous nextCursor. Pages through the current Meta HTML result batch.
trimbooleanNoWhen true, omit cards/images/videos typed arrays (media[] stays). Captapi payloads are already lean vs Meta nested snapshots.
cachebooleanNoSet true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh.

Authentication: send your key as Authorization: Bearer capt_live_.... A typical call costs 2 credits. Pass cache=true for a free 24h cache hit; default is always fresh.

Using an AI agent? This endpoint is the MCP tool facebook_ad_library_search via @captapi/mcp. Set it up →

How it works

  1. 1. Sign up — get 100 free credits, no card required.
  2. 2. Create a key from your dashboard.
  3. 3. Send one request to /v1/ad-library/facebook/search and parse the JSON response.

Use cases

Trend Discovery

Find trending content by keyword or hashtag.

Content Sourcing

Build feeds and playlists programmatically.

Monitoring

Track topics, brands, and competitors.

Research

Sample large sets of content for analysis.

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.

More Facebook Ad Library APIs

Facebook Company Ads APIFacebook Ad Library Search Companies APIFacebook Ad Details APIFacebook Ad Copy API

Ready to use the Facebook Ad Library Search API?

Sign up, grab your key, and make your first call in 60 seconds.

Get started free
Facebook Ad Library Search API | Captapi — Captapi