TikTok Ads Library Actor - EU/UK Ad Search Scraper

Search the public TikTok Ads Library and export structured ad records for supported European region countries.

This Actor is built for marketers, creative researchers, ecommerce operators, and competitive intelligence teams that need TikTok ad transparency data in a clean dataset instead of manually searching the TikTok Commercial Content Library UI.

• Search TikTok Ads Library by keyword, advertiser name, or known ad IDs
• Collect ad IDs, status, titles, media URLs, advertiser fields, impression ranges, dates, targeting fields, and detail-fetch status
• Support Ads Library country inputs for EEA countries, Switzerland, and the United Kingdom
• Run quick search for low-cost result discovery, or enable detail enrichment when you need targeting fields
• Use Apify residential proxy routing for live Ads Library runs
• Export results as JSON, CSV, Excel, XML, or connect them to automation and AI workflows

Why this Actor exists

TikTok's usable no-login transparency surface is the public Commercial Content Library at library.tiktok.com/ads. The page relies on browser context and country-specific UI options, so direct server-side API calls can fail when the required browser state is missing.

This Actor uses a browser-assisted capture/replay workflow for live Ads Library search. It is designed to collect the public ad transparency data that TikTok exposes for supported European region countries and write normalized rows to the Apify dataset.

The current production scope is:

• Source: TikTok Commercial Content Library / TikTok Ads Library
• Primary mode: ads_library_search
• Supported countries: EEA countries, Switzerland, and United Kingdom country codes shown in the Ads Library dropdown
• Fetch path: browser-assisted Ads Library capture with replayed search/detail payloads
• Output: creative-level ad records ready for export, monitoring, and analysis
• Compatibility mode: legacy top_ads mode is kept for older Top Ads workflows, but Ads Library search is the recommended path

What you can do with it

1. Search TikTok Ads Library by keyword

Use keyword search to discover ads related to a product, niche, brand, or offer.

Example input:

{
  "runMode": "real",
  "mode": "ads_library_search",
  "query": "shopify",
  "country": "FR",
  "maxItems": 10,
  "maxPages": 1,
  "quickSearch": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "FR"
  }
}

Example output item:

{
  "adId": "1870189325635585",
  "status": "active",
  "adTitle": "liam_ecom11",
  "adType": "2",
  "adVideoUrl": "https://library.tiktok.com/api/v1/cdn/...",
  "adVideoCover": "https://p16-common-sign.tiktokcdn.com/...",
  "adImageUrls": [],
  "adStartDate": "2026-07-08",
  "adEndDate": "2026-07-08",
  "advertiserId": "",
  "advertiserName": "liam_ecom11",
  "advertiserPaidForBy": null,
  "adImpressions": "0-1K",
  "adTotalRegions": 0,
  "targetingByLocation": [],
  "targetingByAge": [],
  "targetingByGender": [],
  "query": "shopify",
  "searchTerm": "shopify",
  "country": "FR",
  "dataSource": "ads_library_live",
  "detailFetched": false,
  "scrapedAt": "2026-07-11T00:58:46Z"
}

2. Search by advertiser name

Use advertiserName when you want to inspect ads connected to a specific advertiser name.

Example input:

{
  "runMode": "real",
  "mode": "ads_library_search",
  "advertiserName": "Nike",
  "country": "GB",
  "maxItems": 20,
  "maxPages": 1,
  "quickSearch": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "GB"
  }
}

When quickSearch=false, the Actor attempts detail enrichment for fields such as targeting locations, age, gender, advertiser metadata, and detail status when those payloads are available.

3. Fetch known ads by ID

If you already have TikTok Ads Library ad IDs, pass them in adIds to request detail records directly.

Example input:

{
  "runMode": "real",
  "mode": "ads_library_search",
  "country": "FR",
  "adIds": ["1870189325635585"],
  "maxItems": 1,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "FR"
  }
}

4. Monitor creatives over time

Run the Actor on a schedule and compare datasets across days or weeks.

Typical use cases:

• TikTok Ads Library monitoring
• competitor ad research
• creative trend discovery
• ecommerce offer tracking
• dropshipping and DTC creative research
• advertiser transparency checks
• regional ad monitoring for EU and UK markets
• AI-assisted creative analysis workflows

5. Feed TikTok ad data into automation or AI workflows

You can run this Actor from:

• Apify schedules
• Apify API
• Make
• Zapier
• n8n
• Google Sheets pipelines
• MCP-connected AI assistants such as Claude, ChatGPT, or Cursor

Supported Ads Library countries

The country input accepts the country codes currently exposed by TikTok's public Ads Library dropdown for this surface:

• AT Austria
• BE Belgium
• BG Bulgaria
• HR Croatia
• CY Cyprus
• CZ Czech Republic
• DK Denmark
• EE Estonia
• FI Finland
• FR France
• DE Germany
• GR Greece
• HU Hungary
• IS Iceland
• IE Ireland
• IT Italy
• LV Latvia
• LI Liechtenstein
• LT Lithuania
• LU Luxembourg
• MT Malta
• NL Netherlands
• NO Norway
• PL Poland
• PT Portugal
• RO Romania
• SK Slovakia
• SI Slovenia
• ES Spain
• SE Sweden
• CH Switzerland
• GB United Kingdom

Input

Field	Type	Default	Description
runMode	string	fixture	Use fixture for deterministic smoke tests or real for live TikTok Ads Library collection.
mode	string	ads_library_search	Collection mode: ads_library_search, ads_library_probe, or legacy top_ads.
query	string	shopify	Keyword for Ads Library search.
advertiserName	string	empty	Optional advertiser-name search term.
adIds	array of strings	[]	Known TikTok Ads Library ad IDs to fetch directly.
country	string	FR	Ads Library country code. Must be one of the supported EEA, Switzerland, or UK codes listed above.
startDate	string	empty	Optional search start date in YYYY-MM-DD format.
endDate	string	empty	Optional search end date in YYYY-MM-DD format.
timezone	string	UTC	Timezone used in requests and summaries.
sortBy	string	empty	Optional Ads Library sort field.
quickSearch	boolean	false	When true, collect search results and skip detail enrichment.
maxPages	integer	1	Maximum search result pages to fetch.
maxItems	integer	20	Maximum output records.
proxyConfiguration	object	optional	Apify Proxy settings. Use residential proxy country matching the selected country for live runs.
requestTimeoutSecs	integer	30	Timeout for a request or browser capture.
includeDiagnostics	boolean	true	Write diagnostic key-value store records.
fixtures	object	optional	Optional external fixture path overrides. Normal fixture mode uses built-in smoke payloads.
queries	array	optional	Legacy query list for top_ads or ads_library_probe mode.
countryCode	string	ALL	Legacy Top Ads country code.
period	integer	30	Legacy Top Ads time window. Runtime accepts 7, 30, or 180.
orderBy	string	for_you	Legacy Top Ads sort field.
industry, objective, adLanguage, patternLabel	string	empty	Legacy Top Ads filters.

Output

Each dataset item represents one TikTok ad record.

Main Ads Library fields:

• adId
• status
• adTitle
• adType
• adVideoUrl
• adVideoCover
• adImageUrls
• adStartDate
• adEndDate
• advertiserId
• advertiserName
• advertiserTtUserId
• advertiserLocation
• advertiserPaidForBy
• adImpressions
• adTotalRegions
• adEstimatedAudience
• targetingByLocation
• targetingByAge
• targetingByGender
• query
• searchTerm
• advertiserSearchTerm
• country
• dataSource
• detailFetched
• detailError
• scrapedAt

Legacy Top Ads compatibility fields can also appear in top_ads mode:

• materialId
• title
• countryCode
• videoUrl
• brandName
• ctr
• cost

The Actor also writes key-value store records:

• RUN_SUMMARY - final status, mode, run mode, item count, source, proxy metadata, and billing status
• ADS_LIBRARY_SEARCH - normalized search output or detail-by-ID payload summary
• ADS_LIBRARY_SEARCH_CAPTURE - browser-assisted capture evidence when diagnostics are enabled
• ADS_LIBRARY_SEARCH_DIAGNOSTICS - failure diagnostics when live collection fails
• ADS_LIBRARY_PROBE - probe evidence in ads_library_probe mode
• BROWSER_ASSISTED_CAPTURE - browser request metadata for browser-assisted modes
• LIVE_DIAGNOSTICS - live-run diagnostics
• TOP_ADS_* records - legacy Top Ads filters, details, recommendations, metrics, SEO, and related payloads when legacy mode is used

Fixture mode vs real mode

This Actor supports both deterministic fixture runs and live collection.

Fixture mode

fixture mode uses built-in smoke payloads packaged with the Actor. It is useful for:

• release validation
• schema checks
• low-risk output inspection
• confirming the dataset shape without hitting TikTok live pages

Fixture mode does not prove that TikTok is currently returning live data for a selected query or country.

Real mode

real mode uses the browser-assisted TikTok Ads Library collection path.

Recommended live quick-search input:

{
  "runMode": "real",
  "mode": "ads_library_search",
  "query": "shopify",
  "country": "FR",
  "maxItems": 5,
  "maxPages": 1,
  "quickSearch": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "FR"
  }
}

Proxy and country routing

For live Ads Library runs, use an Apify residential proxy country that matches the selected Ads Library country.

Examples:

• country = FR -> France proxy country
• country = DE -> Germany proxy country
• country = GB -> United Kingdom proxy country
• country = ES -> Spain proxy country

Matching the country and proxy country improves consistency because TikTok's Ads Library surface is country-specific.

Live-view web server OpenAPI schema

This Actor includes a real Actor Standby / Live-view web server schema at:

.actor/openapi.json

The schema is published and validated through .actor/actor.json:

{
  "usesStandbyMode": true,
  "webServerSchema": "./openapi.json"
}

Documented Standby endpoints:

• GET / - service information and Apify readiness-probe response
• GET /health - health check
• GET /input-example - fixture and live request examples
• GET /openapi.json - returns the OpenAPI document packaged with the Actor
• POST /search - runs ads_library_search mode from an HTTP request body
• POST /run - runs the Actor with the full input contract, including ads_library_search, ads_library_probe, and legacy top_ads mode

For low-cost validation through Standby, call POST /search with runMode=fixture. For live Ads Library data, use runMode=real with a residential proxy country matching the selected Ads Library country.

How to use on Apify

1. Open the Actor on Apify.
2. Click Try for free.
3. Set runMode to real for live TikTok Ads Library data.
4. Keep mode as ads_library_search unless you specifically need probe or legacy Top Ads mode.
5. Enter query, advertiserName, or adIds.
6. Choose a supported country such as FR, DE, GB, ES, or NL.
7. Keep maxItems and maxPages low for the first run.
8. Enable Apify residential proxy routing with the same country code.
9. Run the Actor and download the dataset as JSON, CSV, Excel, XML, or connect it to another tool.

Example automation input

Low-cost live keyword check:

{
  "runMode": "real",
  "mode": "ads_library_search",
  "query": "shopify",
  "country": "FR",
  "maxItems": 5,
  "maxPages": 1,
  "quickSearch": true,
  "includeDiagnostics": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "FR"
  }
}

Detail-enriched advertiser search:

{
  "runMode": "real",
  "mode": "ads_library_search",
  "advertiserName": "Nike",
  "country": "GB",
  "maxItems": 10,
  "maxPages": 1,
  "quickSearch": false,
  "includeDiagnostics": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "GB"
  }
}

Deterministic fixture smoke test:

{
  "runMode": "fixture",
  "mode": "ads_library_search",
  "query": "shopify",
  "country": "FR",
  "maxItems": 2,
  "maxPages": 1,
  "quickSearch": true
}

Data source

This Actor collects public ad transparency data from:

https://library.tiktok.com/ads

It is intended for current public Ads Library research and monitoring. It does not access private TikTok Ads Manager accounts, private campaign metrics, non-public targeting data, or user-level personal data.

Notes and limits

• TikTok can change Ads Library page structure, request payloads, dropdown country support, or anti-bot behavior.
• Only countries exposed by the public Ads Library dropdown are accepted for ads_library_search country input.
• Some keywords or advertiser names may return no results for a selected country.
• quickSearch=true is cheaper and faster but skips detail enrichment.
• Detail fields depend on whether TikTok returns detail payloads for the ad.
• Live results can vary by country, proxy, time, and TikTok-side availability.
• Use fixture mode for deterministic release checks and real mode for current data.
• Start with low maxItems and maxPages, then scale after confirming the target query returns useful data.

Developer usage

Apify API

curl "https://api.apify.com/v2/acts/lentic_clockss~tiktok-ads-top-ads-actor/runs?token=YOUR_TOKEN" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "runMode": "real",
    "mode": "ads_library_search",
    "query": "shopify",
    "country": "FR",
    "maxItems": 5,
    "maxPages": 1,
    "quickSearch": true
  }'

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("lentic_clockss/tiktok-ads-top-ads-actor").call(run_input={
    "runMode": "real",
    "mode": "ads_library_search",
    "query": "shopify",
    "country": "FR",
    "maxItems": 5,
    "maxPages": 1,
    "quickSearch": True,
})
items = list(client.dataset(run["defaultDatasetId"]).iterate_items())
print(items[:2])

MCP / AI assistants

Use the Actor ID:

lentic_clockss/tiktok-ads-top-ads-actor

Example tool input:

{
  "runMode": "real",
  "mode": "ads_library_search",
  "query": "dropshipping",
  "country": "DE",
  "maxItems": 10,
  "quickSearch": true
}

Summary

Use this Actor when you need a TikTok Ads Library scraper for public EU/UK ad transparency research.

It is optimized for:

• TikTok Ads Library search
• European region ad monitoring
• advertiser and creative research
• ecommerce and DTC creative intelligence
• competitor ad tracking
• public ad transparency exports
• AI-ready TikTok ad datasets for analysis and automation