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

GET/v1/search

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

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>

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,

political

string

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

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

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

–

cached

boolean

–

count

integer

–

errors

object[]

Platforms that failed (not billed)

code

string

–

message

string

–

platform

string

–

platforms

string[]

–

source

string

One of live, history

next_cursorrequired

string

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