Ad history and the archive
Read an ad's versions and active periods, an advertiser's timeline and changes since a date, and search the archive of ads the platforms no longer show.
Ad libraries show what runs now. AdLib records every ad the first time it sees it and every change after, so you can ask what ran last month, also after the platform hides it.
One ad over time
curl "https://api.adlibapi.com/v1/ads/meta:1187430977361020/history" \
-H "X-API-Key: $ADLIB_API_KEY"versions: each change of the creative (text, media, CTA, landing page) withvalid_fromandvalid_to.status_periods: when the ad was active, as start and stop intervals.events:discovered,started,stopped,changedandremoved.reach: EU reach per measurement day for Meta ads shown in the EU. See EU reach over time.
An advertiser over time
GET /v1/advertisers/{id}/timeline: when which ads started and stopped, newest first, withfromandto.GET /v1/advertisers/{id}/changes?since=2026-10-20: new, stopped and changed ads since a point in time, for a weekly digest without webhooks. Addtypes=removedfor ads the platform's library took down.GET /v1/advertisers/{id}/stats: totals, formats, countries, ads first shown per week for the last 12 weeks, run-length distribution and the longest-running ads.
Each timeline or change event costs 1 credit.
Search the archive
Add source=history to a search to query our archive instead of the live libraries. It returns ads the platforms no longer show, and it can sort by run length:
curl "https://api.adlibapi.com/v1/search?advertiser=meta:15087023444&source=history&sort=days_running" \
-H "X-API-Key: $ADLIB_API_KEY"advertiser can also be a name. The archive then searches the advertisers of that name (ignoring case; if none has exactly that name, the ones whose name contains it), on the platforms you pick, and meta.advertisers lists the ids it used. An id is more precise when several advertisers share a name.
curl "https://api.adlibapi.com/v1/search?advertiser=Gymshark&platform=meta,tiktok&source=history" \
-H "X-API-Key: $ADLIB_API_KEY"Ads removed from the libraries
Platforms delete ads from their libraries: Meta takes down ads that broke its rules, advertisers delete ads, and TikTok and LinkedIn drop ads after their retention window. Once an ad is in AdLib it stays. For watched advertisers we look up stopped ads one by one, and when the platform's library no longer has an ad (two empty lookups at least 20 hours apart), we set removed_from_library_at and record a removed event.
curl "https://api.adlibapi.com/v1/search?advertiser=meta:15087023444&source=history&removed=true" \
-H "X-API-Key: $ADLIB_API_KEY"removed=false returns only ads the library still shows. Media of archived ads stays available under our permanent URLs.
Performance signals
Every ad carries derived.signals and derived.stage, computed only from public facts, with no model and no estimate:
| Signal | Rule |
|---|---|
long_running |
Ran more than 30 days |
still_running_90d |
Still active after more than 90 days |
scaled |
Three or more ads of the advertiser share the text |
wide_reach |
EU reach of 100,000 people or more |
multi_country |
Shown in five or more countries |
stage is testing with no signal, scaling with one and proven with two or more. It is null when we don't know how long the ad ran.
Variants: the same text, other creatives
derived.variant_count counts the advertiser's ads in our archive with exactly this ad's text, the ad itself included. To see them, with their images, run times and countries:
curl -H "X-API-Key: $ADLIB_KEY" "https://api.adlibapi.com/v1/ads/meta:1187430977361020/variants?limit=20"The answer is a normal ad list (next_cursor for more), billed per ad like a source=history search. It shows how a brand scales one message: which images it tries, in which countries, and which versions run longest.
How far back
The archive is not a copy of every ad library. We record ads when a customer's request or watchlist reaches them, read the ended ads of an advertiser once when a customer first asks for it, and check daily the advertisers customers keep asking for and larger brands we find ourselves. A smaller advertiser nobody has asked for may have no history with us, and an ad that was only live between two of our checks can be missing. Live search still reads the platforms' libraries directly.
History cannot be filled in for ads a platform had already removed. Put brands on a watchlist to make sure their ads are recorded from now on.
On the free credits you see 12 months of history; after the first credit pack, the full archive. Archived ads last shown more than 12 months ago cost double credits.