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.