API reference · Search

Search ads (cross-platform when `platform` is omitted)

GET/v1/search

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

Exactly one search mode is required: q (keyword), advertiser (name, or our advertiser id <platform>:<id>), or domain. Without platform, all platforms supporting the mode are queried in parallel; platforms that fail are listed in meta.errors (and not billed). source=history searches our own archive instead, including ads that are gone from the platforms.

Example request

Shell
curl "https://api.adlibapi.com/v1/search?q=running%20shoes&platform=meta%2Ctiktok" \
  -H "X-API-Key: $ADLIB_API_KEY"

Send your key in the X-API-Key header. Try it in the explorer.

Parameters

platform
string

Comma-separated platforms; omit for all that support the query. youtube and play are Google ads on YouTube or Google Play (same as platform=google&placement=...)

e.g. meta,google

q
string

Keyword in the ad text

e.g. running shoes

advertiser
string

Advertiser name, or our advertiser id <platform>:<id>. With source=history a name searches the archived advertisers of that name (meta.advertisers lists them)

e.g. Nike

domain
string

Landing page / advertiser domain

e.g. nike.com

country
string

ISO 3166-1 alpha-2

e.g. US

status
string

One of active, inactive, all

default all

from
string

Shown on or after (YYYY-MM-DD)

to
string

Shown before (YYYY-MM-DD)

format
string

One of image, video, carousel, text,

placement
string

Google only: where the ad ran. youtube = YouTube ads; with format=video, YouTube video ads. Limits a live search to Google

One of youtube, search, shopping, maps, play,

political
string

true = only political/issue ads, false = none. Only Meta labels them, so true limits results to Meta

One of true, false,

removed
string

source=history only: true = only ads the platforms' libraries no longer show (taken down, deleted or aged out), which we kept; false = only ads still there

One of true, false,

source
string

One of live, history

default live

sort
string

source=history only: days_running = longest-running ads first (likely winners)

One of newest, days_running

default newest

cursor
string
–
limit
integer

Page size hint (platforms have native page sizes; history honours it exactly)

default 25

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
–
advertisers
string[]

source=history with an advertiser name: the archived advertisers it matched (exact name if any, else name containing it), as <platform>:<id>

cached
boolean
–
count
integer
–
errors
object[]

Platforms that failed (not billed), and code partial_results where a platform answered only part of the page (the ads it returned are billed; the message says what is missing)

code
string
–
message
string
–
platform
string
–
platform_totals
map of integer

Matching ads per platform as the platform reports them, where it does: how much there is beyond this page

platforms
string[]
–
source
string

One of live, history

next_cursorrequired
string

Pass as cursor to get the next page; null = last page