Fetches the ad live from its platform (which also updates our history). If the platform no longer has it, the archived version is returned (meta.source = history).
API reference · Ads
Get one ad
/v1/ads/{id}Try it with your accountOpens in your dashboard, filled in; you see the cost before it runs.
Example request
curl "https://api.adlibapi.com/v1/ads/meta:1187430977361020" \
-H "X-API-Key: $ADLIB_API_KEY"Send your key in the X-API-Key header. Try it in the explorer.
Parameters
idrequiredOur ad id <platform>:<platform_ad_id>
e.g. meta:1234567890
max_ageServe from our archive if we saw the ad within this many seconds (0 = always live)
default 3600
Response
data.advertiserrequireddomainid<platform>:<platform_advertiser_id>
nameplatform_advertiser_idverifieddata.countriesrequiredISO 3166-1 alpha-2
data.creativesrequiredctaheadlinelanding_urlmediatexttypedata.derivedrequireddays_runningis_long_runningdays_running > 30
languageISO 639-1 of the primary ad text
signalsWhy this ad likely performs, from public facts only: long_running (running > 30 days), still_running_90d (active and running > 90 days), scaled (3+ variants with the same text), wide_reach (EU reach >= 100,000), multi_country (shown in 5+ countries)
stagetesting = no signal yet, scaling = one signal, proven = two or more. null when the run length is unknown
One of testing, scaling, proven
variant_countAds sharing this ad's primary text for the same advertiser
data.eu_datarequiredbeneficiarypayerreach_by_countryreach_by_country_rangereach_rangereach_totaltargetingdata.extraPlatform-specific fields
data.first_seen_by_usrequireddata.first_shownrequireddata.formatsrequireddata.idrequiredStable ID: <platform>:<platform_ad_id>
data.impressions_rangerequiredcurrencylowerupperdata.last_seen_by_usrequireddata.last_shownrequireddata.library_urldata.placementsrequireddata.platformrequiredOne of meta, google, tiktok, linkedin, pinterest, x, snapchat, apple, amazon, microsoft
data.platform_ad_idrequireddata.politicalrequiredPolitical or issue ad. Meta only; null where the platform doesn't label it
data.raw_refPointer to the archived raw upstream record
data.removed_from_library_atrequiredWhen the platform's library stopped showing this ad (taken down, deleted by the advertiser or past the library's retention). We keep it; null while the library still has it
data.spend_rangerequiredcurrencylowerupperdata.statusrequiredOne of active, inactive, unknown
metarequiredsourcelive = fetched from the platform now; history = platform no longer serves it
One of live, cache, history