API reference · Ads

Get one ad

GET/v1/ads/{id}

Try it with your accountOpens in your dashboard, filled in; you see the cost before it runs.

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

<platform>:<platform_advertiser_id>

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

signals
string[]

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

stage
string

testing = no signal yet, scaling = one signal, proven = two or more. null when the run length is unknown

One of testing, scaling, proven

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, snapchat, apple, amazon, microsoft

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.removed_from_library_atrequired
datetime

When 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_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