Facebook Ad Details API

What is the Facebook Ad Details API?

Paste a Meta Ad Library ad URL or archive ID and get that creative as clean JSON. Creative fields (text, headline, cta, landingUrl, images[], videos[], advertiser) match a search hit for the same id — use this for ID lookup without paging search. media[] is the canonical URL list (one primary asset per creative, including DCO cards) — resizedUrl and video posters live on images[] / videos[], which fill from cards when Meta leaves the typed arrays empty. DCO {{product.*}} tokens fall back to cards[0] and set textIsFromCard. mediaUrlsExpireAt is the earliest Meta CDN oe= stamp (~5 days). caption is Meta's display domain line under the creative (e.g. blogs.groovewriters.com), not ad copy — text / headline / linkDescription hold the copy. advertiser.id is the Ad Library page id; advertiser.profileId is the facebook.com/{digits} namespace when it differs (url is built from profileId); advertiser.location is keyed null when Meta withholds it. Delivery extras when Meta publishes them (mostly political/issue and EU AAA ads): publisherPlatforms, demographicDistribution[], regionDistribution[], ageCountryGenderReachBreakdown / euTransparency, variantCount (collation), isAaaEligible, spendRange {raw, currency, min, max} (max null on open-ended bands like >$1M). Meta publishes spend and impression ranges only for political and issue ads in regions that require disclosure; commercial advertisers omit both. There is no platforms twin. On commercial ads Meta often withholds those breakdowns — keys stay present as null so the schema is stable. Always 2 credits — native and fallback share one price. fetchPath is native | fallback.

What you get

• ID lookup without paging Ad Library search
• publisherPlatforms when Meta lists them (no platforms twin)
• demographicDistribution[] + regionDistribution[] when published
• EU AAA: euTransparency + ageCountryGenderReachBreakdown
• variantCount (collation) + isAaaEligible + spendRange
• Stable null keys when Meta withholds delivery extras; flat 2 credits

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).

curl "https://api.captapi.com/v1/ad-library/facebook/ad-details?url=https%3A%2F%2Fwww.facebook.com%2Fads%2Flibrary%2F%3Fid%3D317161109571794" \
  -H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."

Example response

{
  "success": true,
  "data": {
    "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-dfw5-2.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=ZqrAiU5uA1sQ7kNvwHsXpf9&_nc_oc=AdqVVq_tCCm9QfdHEQa5d82UKJTt9DT4LxrW9m95vTx7VJLcyuQH74gIZv0WeiJgIfo&_nc_zt=23&_nc_ht=scontent-dfw5-2.xx&_nc_gid=oKi5rqU7-78Y6XFLpAVqvA&_nc_ss=79289&oh=00_AQDIgONmGu5lj1i0jpr_nH9fjb7afatDtlB-wsXtBQNtZQ&oe=6A8F324E"
    },
    "media": [
      "https://video-dfw5-1.xx.fbcdn.net/o1/v/t2/f2/m412/AQNN757NtitUcJnpv0ODeMH6fXo-yFM-X90P2W82Zsrc70oOzST9lrKgscKf21SHBUtZ9pdKMclY8s32B0eRJ7o.mp4?_nc_cat=106&_nc_sid=ef5aa3&_nc_ht=video-dfw5-1.xx.fbcdn.net&_nc_ohc=DeBVZh2ChkAQ7kNvwELM_GV&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuMzQwLmFzaWNfaHExX3NkX3Byb2dyZXNzaXZlIiwieHB2X2Fzc2V0X2lkIjo4MzE0MTAwMzMxNDk2MzYsImFzc2V0X2FnZV9kYXlzIjoyNDEsInZpX3VzZWNhc2VfaWQiOjEwNjgwLCJkdXJhdGlvbl9zIjoxNSwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_gid=oKi5rqU7-78Y6XFLpAVqvA&_nc_ss=79289&_nc_zt=28&oh=00_AQB-CUR53tb21BEWdlRLg5BhAauE3-hDDO9zmz06SvSAdg&oe=6A6D9B48",
      "https://scontent-dfw5-1.xx.fbcdn.net/v/t39.35426-6/120065387_2711663819108220_8472417301728012411_n.jpg?_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=JCEJHIw0engQ7kNvwEcgh1o&_nc_oc=Ado6Dn6wrEd2aZKTiM6OLVJyx_BYbHRC0Bmv70xAZp21Pm2Enab2l80KoUSxQZAs1Ow&_nc_zt=14&_nc_ht=scontent-dfw5-1.xx&_nc_gid=oKi5rqU7-78Y6XFLpAVqvA&_nc_ss=79289&oh=00_AQAw5ZEVUbeJYpBcx6Qa4wV6V-hZRjNvtI487nUdgq8UZA&oe=6A6D850A"
    ]
  }
}

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:

Parameters

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.

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/ad-details and parse the JSON response.

Use cases

Frequently asked questions

More Facebook Ad Library APIs