Facebook Ad Library · Guide

How to run a Facebook Ad Library search

TL;DR

To run a Facebook Ad Library search, sign up for a free Captapi key, then send one 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.

Get your free API key API reference

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": 5,
    "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	SC-compatible. Captapi is already lean vs Meta nested snapshots; when true, omit cards/images/videos typed arrays (media[] stays).
cache	boolean	No	Set true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh. Envelope includes cached + cachedAt on hits.

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. Hits include cached + cachedAt. 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.

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. Hits include cached + cachedAt. 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