Get one ad

GET/v1/ads/{id}

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

Example request

Shell

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

idrequired

path · string

Our ad id <platform>:<platform_ad_id>

e.g. meta:1234567890

max_age

integer

Serve from our archive if we saw the ad within this many seconds (0 = always live)

default 3600

Response

data.advertiserrequired

object

–

domain

string

–

id

string

name

string

–

platform_advertiser_id

string

–

verified

boolean

–

data.countriesrequired

string[]

ISO 3166-1 alpha-2

data.creativesrequired

object[]

–

cta

string

–

headline

string

–

landing_url

string

–

media

object[]

–

text

string

–

type

string

–

data.derivedrequired

object

–

days_running

integer

–

is_long_running

boolean

days_running > 30

language

string

ISO 639-1 of the primary ad text

variant_count

integer

Ads sharing this ad's primary text for the same advertiser

data.eu_datarequired

object

–

beneficiary

string

–

payer

string

–

reach_by_country

map of integer

–

reach_by_country_range

map of object

–

reach_range

object

–

reach_total

integer

–

targeting

object

–

data.extra

map of object

Platform-specific fields

data.first_seen_by_usrequired

datetime

–

data.first_shownrequired

datetime

–

data.formatsrequired

string[]

–

data.idrequired

string

Stable ID: <platform>:<platform_ad_id>

data.impressions_rangerequired

object

–

currency

string

–

lower

integer

–

upper

integer

–

data.last_seen_by_usrequired

datetime

–

data.last_shownrequired

datetime

–

data.library_url

string

–

data.placementsrequired

string[]

–

data.platformrequired

string

One of meta, google, tiktok, linkedin, pinterest, x

data.platform_ad_idrequired

string

–

data.politicalrequired

boolean

Political or issue ad. Meta only; null where the platform doesn't label it

data.raw_ref

string

Pointer to the archived raw upstream record

data.spend_rangerequired

object

–

currency

string

–

lower

integer

–

upper

integer

–

data.statusrequired

string

One of active, inactive, unknown

metarequired

object

–

source

string

live = fetched from the platform now; history = platform no longer serves it

One of live, cache, history