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.
API reference · Search
Search ads (cross-platform when `platform` is omitted)
/v1/searchTry it with your accountOpens in your dashboard, filled in; you see the cost before it runs.
Example request
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
platformComma-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
qKeyword in the ad text
e.g. running shoes
advertiserAdvertiser 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
domainLanding page / advertiser domain
e.g. nike.com
countryISO 3166-1 alpha-2
e.g. US
statusOne of active, inactive, all
default all
fromShown on or after (YYYY-MM-DD)
toShown before (YYYY-MM-DD)
formatOne of image, video, carousel, text,
placementGoogle 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,
politicaltrue = only political/issue ads, false = none. Only Meta labels them, so true limits results to Meta
One of true, false,
removedsource=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,
sourceOne of live, history
default live
sortsource=history only: days_running = longest-running ads first (likely winners)
One of newest, days_running
default newest
cursorlimitPage size hint (platforms have native page sizes; history honours it exactly)
default 25
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
metarequiredadvertiserssource=history with an advertiser name: the archived advertisers it matched (exact name if any, else name containing it), as <platform>:<id>
cachedcounterrorsPlatforms 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)
codemessageplatformplatform_totalsMatching ads per platform as the platform reports them, where it does: how much there is beyond this page
platformssourceOne of live, history
next_cursorrequiredPass as cursor to get the next page; null = last page