Docs

The ad object and ids

Every ad from every platform comes back in the same shape. Ids, dates, status, creatives, EU data and what null means.

AdLib maps each platform's format into one Ad object. A field a platform does not publish is null; we never estimate it. Platform-specific extras are in extra.

Ids

Ids have the form <platform>:<platform id> and never change:

Kind Example
Ad meta:1187430977361020
Advertiser meta:15087023444, google:AR18378488041124659201, tiktok:6876453864464188162

Platforms are meta, google, tiktok, linkedin, pinterest, x, snapchat, apple, amazon and microsoft. YouTube and Google Play ads come from Google's Transparency Center, so they keep google: ids; ask for them with platform=youtube or platform=play.

Main fields

Field Meaning
advertiser id and name of the account that ran the ad
status active, inactive or unknown
first_shown, last_shown Dates the platform publishes for the ad
first_seen_by_us, last_seen_by_us When our crawlers first and last saw it
formats image, video, carousel or text
creatives[] Text, headline, CTA, landing URL and media of each variant
countries, placements Where it ran, as far as published
eu_data EU reach (total and per country), targeting, payer and beneficiary, for ads shown in the EU
spend_range, impressions_range Only where the platform publishes them: spend for political ads; impressions for political ads, every Snapchat ad shown in the EU, and the EU ads of Google, LinkedIn, Microsoft and X
derived.days_running Days between first and last shown, both counted
derived.signals, derived.stage Rule-based performance signals and testing, scaling or proven; see performance signals
removed_from_library_at When the platform's library stopped showing the ad; the ad stays in AdLib. null while it is still there
library_url The ad in the platform's own library

Status

Meta and Snapchat say whether an ad is active, and Google does for some ads. On Amazon an ad counts as active while it was shown in the last 48 hours. TikTok tells us only when you search with status=active or status=inactive; otherwise its ads are unknown. LinkedIn, Pinterest, X, the Apple App Store and Microsoft don't say, so their ads have status unknown; use last_shown and last_seen_by_us with your own rule, for example "shown in the last 3 days".

Media

Image links are always on our own hosts and don't expire, so you can allowlist media.adlibapi.com and api.adlibapi.com. Platform media URLs expire after hours or days.

We store images while answering your request, within a time limit, so url can be on either host. A lookup of one ad waits up to 8 seconds for that, a search up to 3. An image that takes longer gets a link on api.adlibapi.com/m/..., and it finishes in the background.

Field What it holds
url, image media.adlibapi.com once the image is archived. Until then a link on api.adlibapi.com/m/... that archives the image when first opened and redirects to the copy. Links you already stored keep working
url, video media.adlibapi.com for archived videos, which we keep for advertisers on a watchlist. Otherwise the platform's expiring URL
preview_url On our hosts: a 320 px wide thumbnail of an archived image or video, or the poster of a video. For an image not archived yet, the same link as url
original_url The platform's URL, only until the file is archived. It expires, so use it only for reference
sha256 Set once we hold an archived copy; null until then

Media links need no API key, and a browser can load them in an <img> tag. A link answers 404 if the ad was deleted, or if the image was never archived and the platform no longer provides it. For deletions, see the takedown feed. A profile picture in extra.page_profile_picture_url (Meta) works the same way as an image url.

Two sets of dates

first_shown and last_shown come from the platform. first_seen_by_us and last_seen_by_us are ours. When a platform stops listing an ad, its record stays in our archive with both sets of dates. See Ad history and the archive.