TikTok Ads Library Scraper

The Actor searches TikTok's public Ads Library and returns matching ads as structured records: ad text, the dates each ad ran, estimated audience and impressions, and the creative assets themselves. It covers free-text and keyword research, exact-phrase matching, and single-advertiser lookups, and can attach a regional activity report for an advertiser.

TikTok publishes this library to satisfy transparency obligations that follow from its designation as a Very Large Online Platform under the EU's Digital Services Act. Coverage is limited to the European Economic Area, the United Kingdom, and Switzerland; a country code outside those markets returns nothing, however the search is phrased.

Accepted input

Field	Type	Default	Description
startUrl	string	—	An Ads Library search, report, or ad-detail URL. Its filters seed the run.
query	string	running shoes	Brand, product, or phrase to search for.
search_type	enum	free_text	free_text, advertiser, keyword, exact_phrase.
advertiser_id	string	—	Numeric advertiser ID, for advertiser searches.
region	string	GB	Two-letter country code, e.g. GB, DE, FR, ES.
start_time	date	30 days before end	Oldest ad activity date to include.
end_time	date	today	Newest ad activity date to include.
sort	enum	last_shown_desc	Last shown, published, or impressions; ascending or descending.
maxItems	integer	10	Maximum ads saved. 0 removes the limit.
enrichAdDetails	boolean	false	Adds advertiser, targeting, and reach detail per ad.
includeAdvertiserReport	boolean	false	Adds a regional activity report. advertiser searches only.

{
  "query": "running shoes",
  "search_type": "free_text",
  "region": "GB",
  "start_time": "2026-07-01",
  "end_time": "2026-07-24",
  "sort": "last_shown_desc",
  "maxItems": 100
}

A search requires query, region, start_time, and end_time. When one is absent the run stops immediately and names the missing fields rather than issuing a request that cannot succeed. An end_time earlier than start_time is rejected on the same principle.

Supplying startUrl populates these fields from the URL, and any field set explicitly overrides the URL's value. A Creative Center Top Ads URL is rejected here with an explicit message; that shape belongs to TikTok Top Ads Scraper.

Response fields

One record per ad.

Field	Contents
ad_id	TikTok Ads Library ad ID
advertiser_name	Advertiser as named in the library
advertiser_id	Numeric advertiser ID
title	Ad text
region	Market the ad record belongs to
search_query	The query that surfaced this ad
first_shown_at	First date the ad was observed running
last_shown_at	Most recent date the ad was observed running
estimated_audience	Audience size band published by TikTok
impressions	Impression band published by TikTok
spend	Spend band, where published
advertising_objective	Campaign objective
audit_status	TikTok's review status for the ad
video_urls	Video creative URLs
cover_image_urls	Cover image URLs
image_urls	Image creative URLs
ad_detail_url	Library page for the ad
advertiser	Advertiser detail, present with enrichment
targeting	Targeting parameters, present with enrichment
details	Full detail payload, present with enrichment

{
  "ad_id": "1871426970960898",
  "advertiser_name": "Example Brand Ltd",
  "title": "Run further this summer",
  "region": "GB",
  "first_shown_at": "2026-07-02",
  "last_shown_at": "2026-07-23",
  "advertising_objective": "Traffic"
}

Alongside the dataset, a run summary is written to the key-value store under OUTPUT, recording the workflow performed, the number of ads saved, the resolved query and advertiser ID, the region, and the report when one was requested.

Advertiser searches

With search_type set to advertiser, the advertiser name in query is resolved to a numeric ID before the search runs. The resolution requires a single exact name match. When the name is ambiguous or matches nothing exactly, the run stops and lists up to five candidate advertisers with their IDs, so the intended one can be supplied directly through advertiser_id.

includeAdvertiserReport applies only in this mode and is rejected in the others, since the report describes one advertiser's regional distribution and daily publication counts. The report is stored in the run's OUTPUT record rather than the dataset, because it describes the advertiser rather than any single ad.

Behaviour on partial results

Ads are collected in pages of 12, and collection ends when TikTok reports no further pages, returns an empty page, or maxItems is reached. Ads are deduplicated within a run by ad ID, so the same ad surfaced on two pages is saved once.

Enrichment is applied per ad and issues one additional request each. A failed enrichment leaves that record with its search-level fields and no details, is not charged, and does not interrupt the run.

Frequently asked questions

Which countries are covered? The markets where TikTok is obliged to publish an ad repository: the European Economic Area — the 27 EU member states plus Norway, Iceland, and Liechtenstein — along with the United Kingdom and Switzerland. The region field takes those two-letter codes. A code outside that set, US being the common one, returns no ads because the library does not carry them, not because the query was wrong. TikTok has said it intends to widen coverage but has not given a date.

Why did the run stop before making any request? A required field was missing or the dates were inverted. A search needs query, region, start_time, and end_time, and end_time cannot precede start_time. The error names the specific fields, and validation happens before any billable request.

Why was an advertiser search rejected? The advertiser name did not resolve to exactly one match. TikTok's advertiser index contains many similar and regional variants of the same brand, so a name that reads as unambiguous frequently is not. The error lists up to five candidates with their IDs; supplying the right one as advertiser_id removes the ambiguity permanently.

Are impressions and spend exact figures? No. TikTok publishes them as bands rather than precise values, and they are passed through as published rather than converted to a midpoint or estimate. They support comparison between ads, not accounting.

What does enrichAdDetails add, and what does it cost? Advertiser information, targeting parameters, reach, campaign objective, and complete creative metadata, under advertiser, targeting, and details. Each ad costs one additional request and one additional billed event, so a 500-ad run performs 500 extra requests. A first pass without enrichment, followed by a second over the ads that matter, is usually the cheaper route.

Can a URL be pasted instead of setting the filters? Yes. Ads Library search, report, and ad-detail URLs are all accepted in startUrl, and their filters seed the run. Fields set explicitly take precedence over the URL. A Creative Center URL is refused with a message pointing at the other Actor rather than being misread.

Why do some ads have no video URL? Not every ad is a video. Image-only ads populate image_urls and cover_image_urls and leave video_urls empty; the field is absent rather than filled with a placeholder.

Related Actors

Actor	Purpose
TikTok Top Ads Scraper	High-performing ads and creative benchmarks from Creative Center