TikTok Ads Library Scraper

TikTok Ads Library Scraper searches the public TikTok Commercial Content Library for commercial ads that match an advertiser or ad-text query in a supported European market. It returns only source-backed ad identity, ad copy, first and last shown dates, reach and impression bands, media URLs, and search provenance exposed by the public library page. It does not log in, collect private advertiser data, solve challenges, or turn a blocked library response into an invented record.

Get started

1. Open the Actor Store page and select Try for free or open the Input tab.
2. Set the required country to a two-letter EU/EEA or Great Britain code, and replace the smoke-test query with your advertiser or ad-text term.
3. Keep maxItems and maxScrolls small for the first run, then increase them after you inspect the output.
4. Start the Actor, open the dataset, and export the saved ads as JSON, CSV, or Excel. Open Run summary (OUTPUT_SUMMARY) to check the outcome, deduplicated count, and filtered-out reasons.

Input

country is required. The other fields are optional, and the defaults below are ready to use. Unsupported field names and out-of-range values are rejected before the browser starts.

Field	Type	Required?	Default	Meaning
query	string	Optional	Nike	Advertiser name or ad-text query submitted to the public search form, up to 200 characters. The default is a bounded smoke-test value; live availability depends on the public page.
country	string	Required	DE	Two-letter EU/EEA or Great Britain country code used as the ad target region.
maxItems	integer	Optional	50	Global maximum number of distinct rich ad records emitted, from 1 to 200.
maxScrolls	integer	Optional	5	Maximum load-more or scroll attempts on the results page, from 0 to 20.
requestDelayMs	integer	Optional	500	Delay before and between page interactions, from 0 to 5,000 ms.
maxConcurrency	integer	Optional	1	Bounded browser concurrency, from 1 to 3. One is recommended for the interactive Ads Library.
maxRequestRetries	integer	Optional	1	Maximum retries for failed browser requests, from 0 to 2.
requestTimeoutSecs	integer	Optional	60	Per-page request and selector timeout, from 10 to 120 seconds.
proxyConfiguration	object	Optional	Not supplied	Optional Apify Proxy or custom HTTP(S) proxy. Proxy use does not bypass access controls.

Full default input, excluding the optional proxy object:

{
  "query": "Nike",
  "country": "DE",
  "maxItems": 50,
  "maxScrolls": 5,
  "requestDelayMs": 500,
  "maxConcurrency": 1,
  "maxRequestRetries": 1,
  "requestTimeoutSecs": 60
}

The Actor drives the public TikTok Commercial Content Library search form. Advertiser names, ad copy, date ranges, reach bands, and media are read only where the public page renders them. The library's coverage is limited to the markets it publishes; the Actor does not query other advertising databases.

Output

The dataset contains one row per unique public ad. Each row reflects the library page at collection time. Optional values are omitted when the library does not publish them, and the Actor never writes diagnostic or placeholder rows to the dataset. In the saved 2026-10-25 run, adText, impressions, platform, adStatus, and videoUrl were not exposed, so those fields are absent from every saved row.

Field	Type	Availability	Meaning
adId	string	When published	Stable TikTok ad identifier when exposed.
advertiserName	string	When published	Advertiser identity shown by the library.
detailUrl	string	When published	Public ad detail URL.
adText	string	When published	Public ad copy when exposed.
firstShown	string	When published	First shown date or source label, in the library's displayed format.
lastShown	string	When published	Last shown date or source label, in the library's displayed format.
uniqueUsers	string	When published	Public unique-user reach value or band.
impressions	string	When published	Public impression value or band.
platform	string	When published	Platform label shown by the source.
adStatus	string	When published	Business ad status shown by the source.
thumbnailUrl	string	When published	Entity-associated ad thumbnail URL.
videoUrl	string	When published	Entity-associated public video URL when exposed.
source	string	When published	Provenance source identifier.
sourcePageUrl	string	When published	Library search page that produced the record, including its query and region parameters.
query	string	When published	Query used for this search.
country	string	When published	Ad target country code used for this search.
pageNum	integer	When published	Observed source page number; interactive load-more results remain page 1.
position	integer	When published	Position within the observed result batch before global deduplication.
rank	integer	When published	One-based emission rank after global deduplication.
scrapedAt	string	Always	UTC timestamp when the ad row was saved.

The example below is a real saved row from the 2026-10-25 run. The thumbnail URL is the signed CDN URL returned by the library at collection time.

{
  "adId": "1879578146577730",
  "advertiserName": "NIKE Retail B.V.",
  "detailUrl": "https://library.tiktok.com/ads/detail/?ad_id=1879578146577730",
  "firstShown": "10/20/2026",
  "lastShown": "10/24/2026",
  "uniqueUsers": "200K-300K",
  "thumbnailUrl": "https://p16-common-sign.tiktokcdn.com/ad-site-i18n-sg/20261013c7c792c0bae9a7f64a2aac85~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=15480dbb&x-expires=1792980000&x-signature=jPsunDVlCKwvBg2veTcG4Wu3xGY%3D&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1",
  "source": "library.tiktok.com",
  "sourcePageUrl": "https://library.tiktok.com/ads?region=DE&start_time=1790369525249&end_time=1792961525250&adv_name=Nike&adv_biz_ids=&query_type=1&sort_type=create_time,desc&ad_type=0&ad_status=1&ages=all&ad_reach=all&gender=ALL",
  "query": "Nike",
  "country": "DE",
  "pageNum": 1,
  "position": 1,
  "rank": 1,
  "scrapedAt": "2026-10-25T20:52:10.573Z"
}

Run summary

Run summary is stored separately from the dataset in the run's key-value store under OUTPUT_SUMMARY. It reports the search, the number of distinct ads, and counts for candidates that were filtered out or blocked.

Field	Meaning
status	Actor process outcome: SUCCEEDED or FAILED.
dataStatus	Completeness of saved ads: COMPLETE, PARTIAL, NO_RESULTS, or FAILED.
source	Public library host used for the run.
sourceUrl	Final library search URL used for the run, including query and region parameters.
query	Advertiser or ad-text query submitted to the public search form.
country	Two-letter ad target country code used for the run.
requestedMaxItems	Ad limit requested in the input.
normalCount	Distinct ads saved in the dataset.
candidateCount	Ad candidates found on the page before validation and deduplication.
diagnosticCount	Operational issues recorded for the run; these are logged and counted, not written as dataset rows.
blockedCount	Page responses that showed an access block or challenge.
failedRequestCount	Browser or page requests that failed.
pagesProcessed	Result-page loads processed, including the initial load.
filteredOutCount	Candidates rejected because they did not meet the rich public-ad contract.
filteredOutReasons	Object mapping each rejection reason to its candidate count.
fixtureMode	Whether the run parsed a bundled test fixture instead of the live library.
completedAt	Time the summary was written, in ISO UTC.
runStatus	Canonical run status; matches status.

Status	Data status	Meaning
SUCCEEDED	COMPLETE	Ads were saved without an extraction problem.
SUCCEEDED	PARTIAL	Ads were saved, but a later page or extraction problem kept the run from completing. Saved rows remain available.
SUCCEEDED	NO_RESULTS	The library completed cleanly and exposed no ads matching the query.
FAILED	FAILED	A fatal error occurred before any usable ad was saved.

Example OUTPUT_SUMMARY from the 2026-10-25 run:

{
  "status": "SUCCEEDED",
  "dataStatus": "COMPLETE",
  "source": "library.tiktok.com",
  "sourceUrl": "https://library.tiktok.com/ads?region=DE&start_time=1790369525249&end_time=1792961525250&adv_name=Nike&adv_biz_ids=&query_type=1&sort_type=create_time,desc&ad_type=0&ad_status=1&ages=all&ad_reach=all&gender=ALL",
  "query": "Nike",
  "country": "DE",
  "requestedMaxItems": 5,
  "normalCount": 5,
  "candidateCount": 6,
  "diagnosticCount": 0,
  "blockedCount": 0,
  "failedRequestCount": 0,
  "pagesProcessed": 1,
  "filteredOutCount": 0,
  "filteredOutReasons": {},
  "fixtureMode": false,
  "completedAt": "2026-10-25T20:52:11.310Z",
  "runStatus": "SUCCEEDED"
}

Coverage and limitations

The Actor uses the public TikTok Commercial Content Library, not an authenticated advertising API. It searches the advertiser and ad-text fields exposed by the public form and supports only the countries that library publishes, including EU/EEA markets and Great Britain. It honors the visible load-more control up to maxScrolls; the library has no numbered pagination in this workflow, so pageNum stays at 1.

A search can return partial or empty results because the library itself has no matching ads, hides a field, or changes its page structure. A CAPTCHA, login wall, or access denial stops the run rather than being treated as zero ads. Reach and impression values are the bands displayed by the library, not exact measurement data. Detail pages are linked, not opened, so fields that exist only on a detail page are outside this Actor's scope. Signed media URLs can expire after collection.

Usage and support

Cost depends on Apify compute, proxy traffic, browser time, and the number of maxScrolls iterations. Start with a small maxItems, one scroll, and a narrow query; inspect the dataset and the filteredOutReasons in OUTPUT_SUMMARY before scaling. See the Actor's Pricing tab for current account rates.

Use the Actor Issues page to report a problem. Include the run ID, the input used, and the run summary; do not include tokens, cookies, or private data. This Actor is not affiliated with TikTok. Use it only for public data and in accordance with the source's terms, robots guidance, and applicable law. Public pages can contain personal information; use the output only for lawful purposes.