# TikTok Ads Library Scraper - EU/UK Ad Search (`lentic_clockss/tiktok-ads-top-ads-actor`) Actor Search TikTok Ads Library public ad transparency data for supported EEA, Switzerland, and United Kingdom countries, with structured ad, advertiser, media, targeting, and detail-fetch fields. - **URL**: https://apify.com/lentic\_clockss/tiktok-ads-top-ads-actor.md - **Developed by:** [kane liu](https://apify.com/lentic_clockss) (community) - **Categories:** Social media, Automation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.00 / 1,000 result items This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 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: ```json { "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: ```json { "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: ```json { "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: ```json { "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: ```json { "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: ```text .actor/openapi.json ``` The schema is published and validated through `.actor/actor.json`: ```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: ```json { "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: ```json { "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: ```json { "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: ```text 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 ```bash 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 ```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: ```text lentic_clockss/tiktok-ads-top-ads-actor ``` Example tool input: ```json { "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 # Actor input Schema ## `runMode` (type: `string`): Choose fixture or real mode. ## `mode` (type: `string`): Choose ads\_library\_search, ads\_library\_probe, or top\_ads. ## `query` (type: `string`): Keyword for Ads Library search. ## `advertiserName` (type: `string`): Search by advertiser name. ## `adIds` (type: `array`): Fetch records directly by ad ID. ## `country` (type: `string`): Ads Library search country or region. Only TikTok Commercial Content Library dropdown-supported EEA, Switzerland, and United Kingdom country codes are accepted. ## `startDate` (type: `string`): Search start date in YYYY-MM-DD format. ## `endDate` (type: `string`): Search end date in YYYY-MM-DD format. ## `timezone` (type: `string`): Timezone used in requests and summaries. ## `sortBy` (type: `string`): Sort field for Ads Library results. ## `quickSearch` (type: `boolean`): If true, collect search results only and skip detail enrichment. ## `maxPages` (type: `integer`): Maximum number of search result pages to fetch. ## `proxyConfiguration` (type: `object`): Optional Apify Proxy settings. ## `queries` (type: `array`): Query strings used by legacy top\_ads or ads\_library\_probe mode. ## `countryCode` (type: `string`): Country code for the legacy Top Ads page. ## `locale` (type: `string`): Browser page locale. ## `deviceType` (type: `string`): Device type for legacy Top Ads. ## `period` (type: `integer`): Legacy Top Ads time window. Runtime currently accepts 7, 30, or 180. ## `orderBy` (type: `string`): Sort field for legacy Top Ads. ## `maxItems` (type: `integer`): Maximum number of output records. ## `requestTimeoutSecs` (type: `integer`): Timeout for a single request or browser capture. ## `includeDetails` (type: `boolean`): Whether to enable detail enrichment for legacy Top Ads. ## `includeDiagnostics` (type: `boolean`): Whether to write diagnostic KVS records. ## `fixtures` (type: `object`): Optional external fixture file-path override for local validation. When omitted, fixture mode uses built-in smoke payloads packaged in src/default\_fixtures.py. ## `industry` (type: `string`): Industry filter for legacy Top Ads. ## `objective` (type: `string`): Objective filter for legacy Top Ads. ## `adLanguage` (type: `string`): Ad language filter for legacy Top Ads. ## `patternLabel` (type: `string`): Creative label filter for legacy Top Ads. ## Actor input object example ```json { "runMode": "fixture", "mode": "ads_library_search", "query": "shopify", "advertiserName": "", "adIds": [], "country": "FR", "startDate": "", "endDate": "", "timezone": "UTC", "sortBy": "", "quickSearch": false, "maxPages": 1, "countryCode": "ALL", "locale": "en", "deviceType": "pc", "period": 30, "orderBy": "for_you", "maxItems": 20, "requestTimeoutSecs": 30, "includeDetails": true, "includeDiagnostics": true, "industry": "", "objective": "", "adLanguage": "", "patternLabel": "" } ``` # Actor output Schema ## `datasetItems` (type: `string`): Dataset items from the latest Actor run. ## `runSummary` (type: `string`): RUN\_SUMMARY record from the latest Actor run's default key-value store. ## `diagnosticsKeys` (type: `string`): List of keys written to the latest run's default key-value store. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("lentic_clockss/tiktok-ads-top-ads-actor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("lentic_clockss/tiktok-ads-top-ads-actor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call lentic_clockss/tiktok-ads-top-ads-actor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=lentic_clockss/tiktok-ads-top-ads-actor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Scraper - EU/UK Ad Search", "description": "Search TikTok Ads Library public ad transparency data for supported EEA, Switzerland, and United Kingdom countries, with structured ad, advertiser, media, targeting, and detail-fetch fields.", "version": "0.2", "x-build-id": "Dd4xquwsVhsELmDke" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lentic_clockss~tiktok-ads-top-ads-actor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lentic_clockss-tiktok-ads-top-ads-actor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/lentic_clockss~tiktok-ads-top-ads-actor/runs": { "post": { "operationId": "runs-sync-lentic_clockss-tiktok-ads-top-ads-actor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/lentic_clockss~tiktok-ads-top-ads-actor/run-sync": { "post": { "operationId": "run-sync-lentic_clockss-tiktok-ads-top-ads-actor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "runMode": { "title": "Run mode", "enum": [ "fixture", "real" ], "type": "string", "description": "Choose fixture or real mode.", "default": "fixture" }, "mode": { "title": "Collection mode", "enum": [ "ads_library_search", "ads_library_probe", "top_ads" ], "type": "string", "description": "Choose ads_library_search, ads_library_probe, or top_ads.", "default": "ads_library_search" }, "query": { "title": "Search query", "type": "string", "description": "Keyword for Ads Library search.", "default": "shopify" }, "advertiserName": { "title": "Advertiser name", "type": "string", "description": "Search by advertiser name.", "default": "" }, "adIds": { "title": "Ad ID list", "type": "array", "description": "Fetch records directly by ad ID.", "items": { "type": "string", "minLength": 1 }, "default": [] }, "country": { "title": "Target country/region", "enum": [ "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IS", "IE", "IT", "LV", "LI", "LT", "LU", "MT", "NL", "NO", "PL", "PT", "RO", "SK", "SI", "ES", "SE", "CH", "GB" ], "type": "string", "description": "Ads Library search country or region. Only TikTok Commercial Content Library dropdown-supported EEA, Switzerland, and United Kingdom country codes are accepted.", "default": "FR" }, "startDate": { "title": "Start date", "type": "string", "description": "Search start date in YYYY-MM-DD format.", "default": "" }, "endDate": { "title": "End date", "type": "string", "description": "Search end date in YYYY-MM-DD format.", "default": "" }, "timezone": { "title": "Timezone", "type": "string", "description": "Timezone used in requests and summaries.", "default": "UTC" }, "sortBy": { "title": "Sort field", "type": "string", "description": "Sort field for Ads Library results.", "default": "" }, "quickSearch": { "title": "Enable quick search", "type": "boolean", "description": "If true, collect search results only and skip detail enrichment.", "default": false }, "maxPages": { "title": "Maximum pages", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum number of search result pages to fetch.", "default": 1 }, "proxyConfiguration": { "title": "Apify proxy configuration", "type": "object", "description": "Optional Apify Proxy settings.", "properties": { "useApifyProxy": { "title": "Use Apify Proxy", "type": "boolean", "description": "Whether to enable Apify Proxy.", "default": false }, "apifyProxyGroups": { "title": "Proxy groups", "type": "array", "description": "Proxy groups such as RESIDENTIAL.", "default": [], "items": { "type": "string", "minLength": 1 } }, "apifyProxyCountry": { "title": "Proxy country code", "type": "string", "description": "Proxy country code. If provided, it must also be in the same supported set, for example FR, DE, or GB.", "default": "" } } }, "queries": { "title": "Legacy Top Ads query list", "minItems": 1, "type": "array", "description": "Query strings used by legacy top_ads or ads_library_probe mode.", "items": { "type": "string", "minLength": 1 } }, "countryCode": { "title": "Top Ads country code", "minLength": 2, "maxLength": 8, "type": "string", "description": "Country code for the legacy Top Ads page.", "default": "ALL" }, "locale": { "title": "Page locale", "minLength": 2, "maxLength": 10, "type": "string", "description": "Browser page locale.", "default": "en" }, "deviceType": { "title": "Device type", "enum": [ "pc" ], "type": "string", "description": "Device type for legacy Top Ads.", "default": "pc" }, "period": { "title": "Top Ads period", "type": "integer", "description": "Legacy Top Ads time window. Runtime currently accepts 7, 30, or 180.", "default": 30 }, "orderBy": { "title": "Top Ads sort field", "enum": [ "for_you", "impression", "ctr", "play_2s_rate", "play_6s_rate", "cvr", "like" ], "type": "string", "description": "Sort field for legacy Top Ads.", "default": "for_you" }, "maxItems": { "title": "Maximum output items", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of output records.", "default": 20 }, "requestTimeoutSecs": { "title": "Request timeout (seconds)", "minimum": 5, "maximum": 120, "type": "integer", "description": "Timeout for a single request or browser capture.", "default": 30 }, "includeDetails": { "title": "Include Top Ads enrichment", "type": "boolean", "description": "Whether to enable detail enrichment for legacy Top Ads.", "default": true }, "includeDiagnostics": { "title": "Write diagnostics", "type": "boolean", "description": "Whether to write diagnostic KVS records.", "default": true }, "fixtures": { "title": "Fixture configuration", "type": "object", "description": "Optional external fixture file-path override for local validation. When omitted, fixture mode uses built-in smoke payloads packaged in src/default_fixtures.py.", "properties": { "htmlPath": { "title": "HTML path", "type": "string", "description": "Path to the fixture HTML file. Optional; not needed for normal production runs." }, "resultJsonPath": { "title": "Result JSON path", "type": "string", "description": "Path to the fixture result JSON file. Optional; not needed for normal production runs." }, "scrapedAt": { "title": "Scraped-at timestamp", "type": "string", "description": "scrapedAt timestamp used for fixture output." } } }, "industry": { "title": "Top Ads industry filter", "type": "string", "description": "Industry filter for legacy Top Ads.", "default": "" }, "objective": { "title": "Top Ads objective filter", "type": "string", "description": "Objective filter for legacy Top Ads.", "default": "" }, "adLanguage": { "title": "Top Ads ad language filter", "type": "string", "description": "Ad language filter for legacy Top Ads.", "default": "" }, "patternLabel": { "title": "Top Ads creative label filter", "type": "string", "description": "Creative label filter for legacy Top Ads.", "default": "" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```