Docs

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

Shell
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) with valid_from and valid_to.
  • status_periods: when the ad was active, as start and stop intervals.
  • events: discovered, started, stopped, changed and removed.
  • 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, with from and to.
  • 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. Add types=removed for 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:

Shell
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.

Shell
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.

Shell
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:

Shell
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.