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 and x.
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 (mostly political ads) |
derived.days_running |
Days between first and last shown, both counted |
library_url |
The ad in the platform's own library |
Status
Meta, TikTok and X say whether an ad is active. Google, LinkedIn and Pinterest don't, 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
Images are copied to our storage and served from media.adlibapi.com under stable URLs. Platform media URLs expire after hours or days; ours don't. Videos are archived for advertisers on a watchlist.
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.