TikTok Ad Library Scraper — EU Library & Top Ads, Resume & $0-on-Block

Fetch ads from both TikTok transparency surfaces in one Actor — built for large collections that never silently lose data and never charge you for blocked runs.

• EU Commercial Content Library (library.tiktok.com) — every ad delivered to the EU (DSA archive, ~12 months), searchable by advertiser/keyword, with advertiser legal names, first/last shown dates and audience estimates (e.g. 10K-100K unique users).
• Creative Center Top Ads (ads.tiktok.com/business/creativecenter) — a browse feed of global high-performing ads with CTR, likes and video duration, plus direct video URLs. This surface has no keyword search on the login-free tier and returns roughly the top 20 ads per country/period — an honest sample, not an archive.

Why this one

• Resumable pagination — kill or time out a large run and it continues exactly where it stopped. No re-fetching, no double charges. (Built because users of other TikTok ads scrapers asked for exactly this.)
• $0 when blocked — a blocked/rate-limited fetch is detected and not billed. TikTok's search API has a quirk where a bad request returns an empty-but-OK response; this Actor cross-checks against the visible UI total so a soft-fail is never sold to you as "no ads found".
• No silent loss — every work unit is checkpointed; failures land in the dataset as {_error, _reason} records, never dropped.
• Real media files — optionally download creative videos/covers to key-value storage (TikTok CDN hosts only, per-ad cap).
• Clean, stable schema — one flat snake_case row per ad across both surfaces, null-safe, with _meta versioning.

What it does NOT do (honest limits)

• The EU library only contains ads delivered to the EU (that's the legal scope of the archive). Global coverage beyond the EU comes from the Creative Center surface, which is a curated sample of high-performing ads, not an exhaustive archive.
• TikTok does not expose exact spend/impressions for commercial ads. audience_estimate is TikTok's own published range; this Actor does not invent numbers.
• Login-gated data is out of scope by design (logged-out public surfaces only).

Input

Field	Meaning
queries	Advertiser names or keywords (required; used by the CCL surface — Creative Center is a browse-only feed)
surfaces	["ccl"] (EU library, default) and/or ["cc"] (Creative Center Top Ads, one work unit per country)
countries	CCL: target country ISO or all. CC: ISO (no all; falls back to US)
lookbackDays	CCL last-shown window, max 365
mode	snapshot or snapshot_with_media (also downloads creatives)
maxItems / maxBudgetUsd	Hard caps — you are never charged beyond them (persist across resumes)
maxAdsPerUnit	Cap of ads fetched per (surface × query × country) work unit (advanced, default 600)
ccPeriodDays	Creative Center Top Ads ranking window in days — 7, 30, or 180 (default 30)
useResidentialProxy	Off by default (TikTok libraries are reachable from datacenter egress)

Output (one row per ad)

{
  "ad_id": "1873877803725954",
  "country": "DE",
  "surface": "commercial_content_library",
  "advertiser_name": "NIKE Retail B.V.",
  "title": "Une rentrée signée Nike",
  "first_shown": "2026-08-20", "last_shown": "2026-08-31", "days_shown": 11,
  "audience_estimate": "10K-100K",
  "metrics": { "impression": 0 },
  "industry": null, "objective": null, "audit_status": "1",
  "detail_url": "https://library.tiktok.com/ads/detail/?ad_id=1873877803725954",
  "media": [{ "kind": "video", "url": "...", "stored_key": "media_video_ab12.mp4" }],
  "image_urls": ["https://p19-...tiktokcdn.com/..."],
  "video_urls": ["https://library.tiktok.com/api/v1/cdn/..."],
  "_meta": { "_scraped_at": "2026-09-02T00:00:00Z", "_source_url": "...", "_actor_version": "<actor build version>", "_schema_version": "<schema version>" }
}

Creative Center rows carry metrics: { ctr, like, video_duration } (plus cost_tier, which TikTok only fills for roughly half of ads and whose scale it does not publish) and industry/objective keys instead of dates.

Pricing (pay-per-event)

Event	Price
actor-start	$0.02
ad-scraped	$0.001 per ad
media-downloaded	$0.005 per file (only in snapshot_with_media)

You are not charged for blocked runs, empty results, or ads beyond maxItems / maxBudgetUsd.

How it works (and why it keeps working)

The Actor drives a real headless browser over the public, logged-out pages and collects the JSON responses the page itself requests — no signature reverse-engineering, no login, no CAPTCHA solving. When TikTok rotates its request-signing internals, this Actor keeps working because the page's own JavaScript does the signing. UI selectors are isolated in one place (src/platform/browserCollector.js) for quick fixes if the layout changes.

Reliability core (billing safety, resume, block/empty classification) is the same adversarially-reviewed engine used by our Meta Ad Library and Google Ads Transparency actors: mid-run kill → no double charge & no data loss; blocked/rate-limited/empty → $0; push failure → not billed; integer micro-dollar accounting. npm test runs the full suite (incl. a real-package API-surface check) against real captured API responses with no network access.