/v1/facebook/adLibrary/ad

GET

Ad Details

Get Facebook Ad Library details by ID or URL. For ads with multiple versions, use the title in cards.

Credit cost	Default: 1 credit How charges are determined Cost is decided per call, not per endpoint: the same operation can cost different amounts depending on what it returns. A call that fails costs 0 credits. A result served from cache costs 0 credits. `default` is the cost when no rule matches. Rules are evaluated in order and the first whose conditions all hold wins. A `when` condition is one of: `param` (the request parameter is true), `outcome` (the classifier's outcome), `empty` / `nonEmpty` (a response field is empty and absent, or a non-empty array or string), `flag` (a response field is exactly true). A cost of `{ perStartedMinute: n, of: [fields] }` is n x max(1, ceil(seconds / 60)), so even a short result bills at least one minute.
Cache support	Use a cached response this old or newer for 0 credits. If none is available, fetch live at the endpoint’s normal price.
Pagination	No explicit pagination metadata in the published contract. Consult the parameters and response fields below.

Parameters

Name	Location / required	Schema
`id` Facebook Ad Id	query / optional	`string`
`url` Facebook Ad URL	query / optional	`string`
`allow_long_transcription` Allow AI transcription over 2 minutes. Paid rates apply to short videos too. Enable transcription separately.	query / optional	`boolean`
`get_transcript` Set true to include a transcript. Default AI up to 2 minutes is included in the base price. allow_long_transcription=true adds 10 credits per AI minute, rounded up, even for short videos.	query / optional	`boolean`
`trim` Set true for a trimmed response.	query / optional	`boolean`
`cache_max_age` Use a cached response this old or newer for 0 credits. If none is available, fetch live at the endpoint’s normal price.	query / optional	`string` Allowed values `["1d","3d","7d","14d","30d"]`

Request examples

Replace placeholder values and supply your own API key. For operations with a request body, populate the body using the schema above.

cURL

curl --request GET 'https://api.fetchproof.com/v1/facebook/adLibrary/ad' \
  --header 'x-api-key: YOUR_API_KEY'

JavaScript

const response = await fetch("https://api.fetchproof.com/v1/facebook/adLibrary/ad", {
  method: 'GET',
  headers: { 'x-api-key': process.env.FETCHPROOF_API_KEY }
});
console.log(await response.text());

Python

import os
import requests

response = requests.get("https://api.fetchproof.com/v1/facebook/adLibrary/ad",
    headers={"x-api-key": os.environ["FETCHPROOF_API_KEY"]})
print(response.text)

Responses

200Success. Envelope: success / credits_remaining / credits_charged.

application/json

object

successrequired

boolean

credits_remainingrequired

integer

credits_chargedrequired

integer

adidoptional

integer

adArchiveIDrequired

integer

archiveTypesoptional

array

categoriesoptional

array

Array items

integer

containsDigitallyCreatedMediaoptional

boolean

containsSensitiveContentoptional

boolean

collationCountoptional

null

collationIDoptional

null

currencyoptional

string

endDaterequired

integer

entityTypeoptional

string

fevInfooptional

null

finServAdDataoptional

object

is_deemed_finservrequired

boolean

is_limited_deliveryrequired

boolean

gatedTypeoptional

string

hasUserReportedoptional

boolean

hiddenSafetyDataoptional

boolean

hideDataStatusoptional

string

impressionsWithIndexoptional

object

impressionsTextrequired

null

impressionsIndexrequired

integer

isAAAEligiblerequired

boolean

isAdAccountActionedoptional

boolean

isActiverequired

boolean

isProfilePageoptional

boolean

pageIDrequired

integer

pageInfooptional

null

pageIsDeletedoptional

boolean

pageNamerequired

string

politicalCountriesrequired

array

reachEstimaterequired

null

regionalRegulationDataoptional

object

finservrequired

object

is_deemed_finservrequired

boolean

is_limited_deliveryrequired

boolean

tw_anti_scamrequired

object

is_limited_deliveryrequired

boolean

reportCountoptional

null

snapshotrequired

object

ad_creative_idrequired

integer

cardsrequired

array

body_translationsrequired

object

bylinerequired

null

captionrequired

string

cta_textrequired

string

dynamic_item_flagsrequired

object

dynamic_versionsrequired

null

edited_snapshotsrequired

array

effective_authorization_categoryrequired

string

eventrequired

array

extra_imagesrequired

array

Array items

object

original_image_handlerequired

string

resized_image_handlerequired

string

extra_linksrequired

array

Array items

string

extra_textsrequired

array

extra_videosrequired

array

instagram_shopping_productsrequired

array

display_formatrequired

string

titlerequired

string

link_descriptionrequired

null

link_urlrequired

string

page_welcome_messagerequired

null

imagesrequired

array

Array items

object

original_image_urlrequired

string

resized_image_urlrequired

string

watermarked_resized_image_urlrequired

string

image_cropsrequired

object

videosrequired

array

Array items

object

video_hd_urlrequired

string

video_sd_urlrequired

string

watermarked_video_sd_urlrequired

string

watermarked_video_hd_urlrequired

string

video_preview_image_urlrequired

string

creation_timerequired

integer

page_idrequired

integer

page_namerequired

string

page_profile_picture_urlrequired

string

page_categoriesrequired

object

197251360301109optional

string

1713352298924731optional

string

page_entity_typerequired

string

page_is_profile_pagerequired

boolean

instagram_actor_namerequired

string

instagram_profile_pic_urlrequired

string

instagram_urlrequired

string

instagram_handlerequired

string

is_resharedrequired

boolean

versionrequired

integer

bodyrequired

string

brazil_tax_idrequired

null

branded_contentrequired

object

page_idrequired

integer

page_namerequired

string

page_profile_picture_urlrequired

string

page_categoriesrequired

object

197251360301109required

string

current_page_namerequired

string

page_profile_urirequired

string

page_is_deletedrequired

boolean

current_page_namerequired

string

disclaimer_labelrequired

null

page_like_countrequired

integer

page_profile_urirequired

string

page_is_deletedrequired

boolean

root_reshared_postrequired

null

cta_typerequired

string

additional_inforequired

null

ec_certificatesrequired

null

country_iso_coderequired

null

instagram_branded_contentrequired

object

instagram_bc_sponsor_idrequired

string

instagram_bc_sponsor_namerequired

string

spendrequired

null

startDaterequired

integer

stateMediaRunLabeloptional

null

publisherPlatformrequired

array

Array items

string

menuItemsoptional

array

targetedOrReachedCountriesoptional

array

totalActiveTimerequired

integer

urlrequired

string

startDateStringrequired

string

{
  "format": "date-time"
}

endDateStringrequired

string

{
  "format": "date-time"
}

aaa_inforequired

object

targets_eurequired

boolean

location_audiencerequired

array

Array items

object

namerequired

string

num_obfuscatedrequired

integer

typerequired

string

excludedrequired

boolean

gender_audiencerequired

string

age_audiencerequired

object

minrequired

integer

maxrequired

integer

eu_total_reachrequired

integer

age_country_gender_reach_breakdownrequired

array

Array items

object

countryrequired

string

age_gender_breakdownsrequired

array

Array items

object

age_rangerequired

string

malerequired

integer

femalerequired

integer

unknownrequired

integer

payer_beneficiary_datarequired

array

Array items

object

payerrequired

string

beneficiaryrequired

string

has_violating_payer_beneficiaryrequired

boolean

is_ad_taken_downrequired

boolean

cachedoptional

boolean

cached_atoptional

string

{
  "format": "date-time"
}

401Invalid or missing x-api-key

402No credits remaining

403Upstream denied (age gate, audience controls)

404Resource or endpoint not found

429Rate limited