One ad in full: copy, call to action, destination, every creative version in its ad group, the advertiser profile, and EU transparency reach broken down by country, age and gender.

POST /ad-detail Ads

https://api.fetchlayer.dev/facebook-ad-library/ad-detail

OpenAPI JSON

Headers

Authorization string required

Bearer token — your FetchLayer API key.

Parameters

ad string required

Ad archive id, or an Ad Library URL containing one.

country string optional

Two-letter country code, or ALL.

includeVariations boolean optional

Also fetch every other creative version in the same ad group. (default: true)

format string optional

json or markdown, lowercase; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON. (default: json)

timeoutMs integer optional

Time limit for the whole request, in milliseconds (1000–120000), counted from its arrival, time spent waiting in the queue included; a value outside that range is a 400. When it runs out, a paged request returns what it has with nextCursor and a note, billed for the pages it delivered; a request with nothing to return yet fails with a 503 you can retry, marked with the response header X-Timeout-Source: caller. Left out, the request runs as long as it needs.

Response Fields

ad-detail

Get one ad in full

adArchiveId string

The resolved ad archive id.

ad object

The full ad record, including its creative.

advertiserProfile object | null

Profile of the page running the ad; null when it was not looked up, with a note saying why.

euTransparency object | null

For ads carrying EU transparency reporting: totalReach, the age, gender and location audience, and reach by country and age range. null for other ads.

euTransparency.genderAudience string[]

The genders the ad was shown to; an ad shown to everyone is ["All"].

euTransparency.ageCountryGenderReachBreakdown object[]

Reach by country and age range. Each entry’s reach is the total for that age range across genders, with maleReach, femaleReach and unknownReach beside it.

variations object[]

The creative versions in the ad’s group, of any status, each a full ad record — so its length can differ from collationCount. Empty when the ad has no other versions. On the rare ad whose versions cannot be checked, the note says so and the list may be incomplete; under a short timeoutMs, notes names any part not looked up in time (versions, advertiser profile, EU transparency).

variationCount integer

How many creative versions the ad group carries.

violationTypes string[]

Policy violations Meta has recorded against the ad.

Request

curl -X POST "https://api.fetchlayer.dev/facebook-ad-library/ad-detail" \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"ad":"1702938977100376","includeVariations":true}'

Response

{
  "adArchiveId": "1702938977100376",
  "variationCount": 4,
  "ad": {
    "creative": {
      "title": "{{product.name}}",
      "body": "Bring sports more fully into your day with the Nike App.",
      "ctaText": "Install now"
    }
  }
}

{
  "error": "Invalid API key"
}