# TikTok Ads Library Scraper Pro (`crawlerbros/tiktok-ads-library-scraper-pro`) Actor Scrape TikTok's public ad transparency library by query, advertiser, region, and date range. Pulls ad text, video URL, advertiser, impression buckets, and per-region/age/gender targeting. Pro filters: regionFilter, industryFilter, minImpressions, daysActive derived field. - **URL**: https://apify.com/crawlerbros/tiktok-ads-library-scraper-pro.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Social media, Developer tools, Other - **Stats:** 9 total users, 6 monthly users, 100.0% runs succeeded, 23 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $1.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 Scraper Pro Scrape TikTok's public Ad Library (DSA transparency database) at scale. Extract every ad currently shown in EU/EEA, UK, Switzerland, and Turkey — with full per-ad targeting breakdowns, advertiser identification, creative URLs, and impression data. ### What is TikTok Ads Library Scraper Pro? TikTok publishes its full ad transparency database under the EU Digital Services Act (DSA). This actor calls TikTok's official `library.tiktok.com` JSON API directly — no browser, no cookies, no login — and emits clean, structured data ready for analysis. **No browser. No login. Proxy rotation enabled by default** to reduce TikTok's per-IP `limit exceed` rate limits on cloud runs. #### What you get out of every ad - **Ad identity** — `adId`, `adUrl`, `adType` (video / image), `adFormat` (single video / carousel / spark ad / image) - **Creative assets** — `adVideoUrl`, `adVideoCover`, `adImages[]`, plus a full `adVideos[]` list for carousels - **Dates** — `adStartDate`, `adEndDate`, derived `daysActive`, `avgImpressionsPerDay` - **Reach** — `adImpressions` (TikTok's bucket like `10K-100K`), exact `adImpressionsExact` when present, `adSpent` - **Advertiser identity** — `advertiserName`, `advertiserBusinessName`, `advertiserBusinessId`, `advertiserCountry` (registry country), `advertiserSponsor` (different from name when ad runs through an agency), `advertiserTikTokUser` (linked TT account when present), `advertiserIndustry` - **Targeting breakdown** — per-region `targetingByLocation[]`, per-region age buckets in `targetingByAge[]`, per-region gender selection in `targetingByGender[]`, total `targetAudienceSize`, plus `targetingTotalRegions`, `targetingTotalImpressions` - **Audience targeting flags** — `audienceTargeting` (Yes/No), `interestTargeting`, `videoInteractionsTargeting`, `creatorInteractionsTargeting` (only emitted when non-empty) - **Compliance** — `auditStatus`, `auditStatusLabel` (`approved`, `rejected`, `in_review`, `removed`), `sorAuditStatus`, `rejectionInfo`, `auditReasons` - **Misc** — `ctaText`, `landingPageUrl`, `adLanguages`, `adPlatforms` (TikTok / CapCut / Pangle / Lemon8), `creativeId`, `creativeName`, `dataSource`, `commercialContentIndicator`, `showMode` ### How to use #### Quick start ```json { "query": "shopify", "region": "DE", "maxItems": 100 } ```` #### Filter by advertiser only ```json { "advertiserName": "Temu", "region": "all", "maxItems": 500 } ``` #### Direct lookup by ad ID ```json { "adIds": ["1863424159438849", "1863615078571137"] } ``` #### Pro filters — surgical narrowing of the result set ```json { "query": "supplements", "region": "all", "regionFilter": ["DE", "FR", "ES"], "industryFilter": ["health", "beauty"], "languageFilter": ["en", "de"], "ctaFilter": ["Shop Now", "Buy"], "minImpressions": 50000, "maxItems": 1000 } ``` #### Input parameters | Parameter | Type | Default | Description | | ----------------- | ------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `query` | String | `shopify` | Free-text search — company name, domain, or ad text. Empty = browse all ads. | | `adIds` | Array | `[]` | Direct list of TikTok ad IDs. Bypasses search and fetches each ad's detail page directly. | | `advertiserName` | String | `""` | Filter by advertiser name (substring match). | | `region` | String | `all` | TikTok ad region code. EU/EEA + UK/CH/TR are covered (DSA mandate). Use `all` for cross-region. | | `startDate` | String | 1 year ago | Earliest ad start date (`YYYY-MM-DD`). | | `endDate` | String | today | Latest ad end date (`YYYY-MM-DD`). | | `sortBy` | Enum | `last_shown_date,desc` | One of: `last_shown_date`/`create_time`/`impression` × `asc`/`desc`. | | `quickSearch` | Boolean | `true` | When true, skip the per-ad detail fetch — faster, but omits targeting / advertiser registry / audience fields. Set `false` for full detail enrichment. | | `maxItems` | Integer | `10` | Hard cap on emitted ads (1-5000). | | `regionFilter` | Array | `[]` | **Pro.** Only emit ads that target one of these regions (matched against `targetingByLocation`). | | `industryFilter` | Array | `[]` | **Pro.** Only emit ads whose advertiser industry contains one of these substrings. | | `languageFilter` | Array | `[]` | **Pro.** Only emit ads in these languages (e.g. `en`, `de`). Ads without a detected language are kept (avoids over-filtering). | | `ctaFilter` | Array | `[]` | **Pro.** Only emit ads whose CTA button text contains one of these substrings (e.g. `Shop Now`, `Learn More`). Ads without a CTA are dropped. | | `minImpressions` | Integer | unset | **Pro.** Drop ads below this many impressions (numeric value parsed from TikTok's bucket like `10K-100K`). | | `useApifyProxy` | Boolean | `true` | Routes requests through Apify's proxy pool and rotates sessions when TikTok returns `limit exceed`. | | `requestDelaySecs`| Integer | `1` | Delay between API requests. Increase this for slower, gentler runs when TikTok is rate-limiting sampled IPs. | | `timezone` | String | `UTC` | IANA timezone for date-range bucketing. | Default empty-input runs use `query="shopify"`, `quickSearch=true`, and `maxItems=10` so Apify's daily test emits real records quickly when TikTok is not rate-limiting the sampled IPs. ### Output Each ad is pushed as a separate dataset row. Empty fields are omitted (no nulls). Sample row: ```json { "recordType": "ad", "adId": "1863424159438849", "adUrl": "https://library.tiktok.com/ads/detail/?ad_id=1863424159438849", "adType": "video", "adFormat": "single_video", "advertiserName": "STYLEGRID TRADING LIMITED", "advertiserBusinessName": "STYLEGRID TRADING LIMITED", "advertiserBusinessId": "7477502534530105361", "advertiserId": "7477502534530105361", "advertiserCountry": "Hong Kong", "advertiserSponsor": "LINGTOK LIMITED", "adVideoUrl": "https://library.tiktok.com/api/v1/cdn/.../video.mp4", "adVideoCover": "https://p16-common-sign.tiktokcdn.com/.../cover.jpeg", "adImages": ["https://p16-common-sign.tiktokcdn.com/.../cover.jpeg"], "adStartDate": "2025-08-12", "adEndDate": "2026-04-29", "adImpressions": "10K-100K", "auditStatus": "1", "auditStatusLabel": "approved", "sorAuditStatus": "1", "showMode": 1, "targetingByLocation": [ { "region": "DE", "impressions": "32K" } ], "targetingTotalRegions": 1, "targetingTotalImpressions": "10K-100K", "targetingByAge": [ { "region": "DE", "ages": ["25-34", "35-44", "45-54", "55+"] } ], "targetingByGender": [ { "region": "DE", "genders": ["female", "male", "unknown"] } ], "targetAudienceSize": "17.4M-21.2M", "audienceTargeting": "No", "daysActive": 261, "avgImpressionsPerDay": 38, "scrapedAt": "2026-04-29T11:39:32+00:00" } ``` #### Output field reference | Field | Type | Description | | -------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `adId` | String | TikTok's internal ad ID. | | `adUrl` | String | Public ad library detail URL. | | `adType` | String | `video` or `image`. | | `adFormat` | String | Granular format — `single_video`, `carousel`, `spark_ad`, `image`. | | `advertiserName` | String | Advertiser display name (from search card). | | `advertiserBusinessName` | String | Registered advertiser business name (from detail). | | `advertiserBusinessId` | String | TikTok's internal advertiser business ID. | | `advertiserId` | String | Alias of `advertiserBusinessId` (kept for backwards compatibility). | | `advertiserCountry` | String | Registry country of the advertiser legal entity (e.g., `Germany`, `Hong Kong`). | | `advertiserSponsor` | String | Sponsor / agency that placed the ad on the advertiser's behalf — often differs from `advertiserName`. | | `advertiserTikTokUser` | Object | Linked TikTok user account (`id`, `nickname`, `uniqueId`, `avatarUrl`) when present. | | `advertiserIndustry` | String | Industry classification (when published). | | `adVideoUrl` | String | Direct URL to the ad's primary video. | | `adVideoCover` | String | Cover image URL. | | `adVideos` | Array | All videos for carousel ads, each `{videoUrl, coverImage}`. | | `adImages` | Array | All static images. | | `adStartDate` | String | First-shown date (`YYYY-MM-DD`, UTC). | | `adEndDate` | String | Last-shown date (`YYYY-MM-DD`, UTC). | | `adImpressions` | String | TikTok's impression bucket (e.g. `10K-100K`, `1M-10M`). | | `adImpressionsExact` | Integer | Exact impression count if TikTok publishes one. | | `adSpent` | String | Spend bucket if TikTok publishes one. | | `auditStatus` | String | TikTok's audit code. | | `auditStatusLabel` | String | Human label — `approved`, `rejected`, `in_review`, `removed`. | | `sorAuditStatus` | String | Statement-of-Reasons audit status (DSA Article 17 compliance). | | `rejectionInfo` | Object | Rejection-reason payload (only if non-empty). | | `auditReasons` | Array | List of audit-reason codes (only if present). | | `showMode` | Integer | Raw show-mode code from TikTok. | | `targetingByLocation` | Array | `[{region, impressions}]` per-region impression breakdown. | | `targetingTotalRegions` | Integer | Number of distinct regions the ad was shown in. | | `targetingTotalImpressions` | String | Aggregate impression bucket across all regions. | | `targetingByAge` | Array | `[{region, ages: [...]}]` — list of age buckets selected per region. | | `targetingByGender` | Array | `[{region, genders: [...]}]` — list of genders selected per region. | | `targetAudienceSize` | String | Total addressable audience bucket (e.g. `22.0M-26.9M`). | | `audienceTargeting` | String | `Yes` if a custom-audience was used, else `No`. | | `interestTargeting` | String | Interest categories targeted (only if non-empty). | | `videoInteractionsTargeting` | String | Video-interaction targeting rule (only if non-empty). | | `creatorInteractionsTargeting` | String | Creator-interaction targeting rule (only if non-empty). | | `ctaText` | String | Call-to-action button label (e.g. `Shop Now`). | | `landingPageUrl` | String | Landing-page URL the CTA links to. | | `adLanguages` | Array | Detected language(s) (e.g. `["en", "de"]`). | | `adPlatforms` | Array | Platforms the ad ran on (`TikTok`, `CapCut`, `Pangle`, `Lemon8`). | | `creativeId` | String | TikTok creative ID. | | `creativeName` | String | TikTok creative name. | | `dataSource` | String | `DSA-transparency` or `commercial-content`. | | `commercialContentIndicator` | Boolean | Set when ad is flagged as commercial-content. | | `daysActive` | Integer | Derived: `adEndDate - adStartDate + 1`. | | `avgImpressionsPerDay` | Integer | Derived: `adImpressions` lower bound ÷ `daysActive`. | | `scrapedAt` | String | ISO timestamp when this row was emitted. | > Empty fields are stripped — only fields with actual data appear in each row. ### FAQ #### Why are non-EU regions not supported? The TikTok Ad Library is a DSA (EU Digital Services Act) transparency mandate. TikTok only publishes ads shown in EU/EEA + UK/CH/TR. The actor returns HTTP 400 for unsupported regions, so we restrict the input enum. #### Do I need a proxy? Proxy rotation is enabled by default because TikTok often rate-limits cloud datacenter IPs with a `limit exceed` response. If every sampled proxy session is capped, retry after the cooldown window, lower `maxItems`, or increase `requestDelaySecs`. #### What's the difference between `quickSearch=true` and `quickSearch=false`? `quickSearch=true` skips the per-ad detail fetch and emits only the search-card data — faster (1 request per page of 50 ads), but omits targeting breakdowns, advertiser registry country, sponsor, and audience targeting. `quickSearch=false` makes one extra detail-endpoint call per ad to enrich each row with the full targeting breakdown. #### How fresh is the data? TikTok's ad library refreshes within minutes of an ad being shown. The `adStartDate` / `adEndDate` reflect the current display window. #### Why do some ads have no `adVideoUrl` / `adImages`? Some ads are fully removed (`auditStatus="2"` rejected) but still listed in the transparency database with creative assets stripped. Those rows still expose advertiser identity and targeting metadata. #### Can I scrape spark ads (organic-style)? Yes. Set `region` and a query that matches the advertiser. Spark ads emit with `adFormat="spark_ad"`. ### Use cases - **Competitive intelligence** — Track every ad your competitors run in Europe, including targeting strategy. - **Creative analysis** — Download competitor creative, study CTAs, formats, and language strategies. - **Sponsorship research** — Identify which agencies (`advertiserSponsor`) place ads for which brands. - **Compliance / DSA monitoring** — Flag rejected or in-review ads, audit reasons, sponsor disclosures. - **Market sizing** — Aggregate impression buckets per industry, region, age bucket. - **Influencer due diligence** — Inspect `advertiserTikTokUser` to see which brands run paid amplification on a creator's content. ### Legal This actor only extracts publicly-available data from TikTok's official transparency portal. Ensure your downstream use complies with TikTok's Terms of Service, GDPR, and applicable local laws. ### Related scrapers - TikTok Profile Scraper — profile and video metadata - TikTok Comments Scraper — full comment threads with replies - TikTok Hashtag Scraper — videos by hashtag - TikTok Post Scraper — video downloads with metadata # Actor input Schema ## `query` (type: `string`): Free-text query — company name, domain, or ad text. Leave empty to browse all ads. ## `adIds` (type: `array`): Direct list of TikTok ad IDs. Bypasses search and fetches each ad's detail page directly. ## `advertiserName` (type: `string`): Filter by advertiser name (substring match). ## `region` (type: `string`): TikTok ad region. The library covers EU/EEA + UK/CH/TR (DSA transparency). Use `all` for all-region search. ## `startDate` (type: `string`): Earliest ad start date. Default: 1 year ago. ## `endDate` (type: `string`): Latest ad end date. Default: today. ## `sortBy` (type: `string`): How to sort results. ## `quickSearch` (type: `boolean`): When true, skip the ad-detail fetch and only return data from the listing card. Faster but omits some fields (full targeting breakdown). ## `maxItems` (type: `integer`): Hard cap on emitted ads. ## `regionFilter` (type: `array`): Only emit ads that target one of these regions. Case-insensitive substring match against `targetingByLocation`. ## `minImpressions` (type: `integer`): Drop ads with fewer than this many impressions (numeric value parsed from TikTok's bucket like `10K-100K`). ## `industryFilter` (type: `array`): Only emit ads whose advertiser industry contains one of these substrings. ## `languageFilter` (type: `array`): Only emit ads in these languages (matched case-insensitively against the `adLanguages` field, e.g. `en`, `de`, `fr`). Ads without a detected language are kept. Most effective with `quickSearch=false`. ## `ctaFilter` (type: `array`): Only emit ads whose call-to-action button text contains one of these substrings (case-insensitive — e.g. `Shop Now`, `Learn More`, `Sign Up`). Ads without a CTA are dropped. Requires `quickSearch=false` — CTA data is only available from the detail page. ## `useApifyProxy` (type: `boolean`): Route requests through Apify's residential proxy pool with EU exit IPs. Strongly recommended — TikTok's API aggressively rate-limits per-IP and cloud datacenter IPs hit the cap fast. The actor automatically rotates the proxy session on 'limit exceed' errors. ## `requestDelaySecs` (type: `integer`): Pause between successive API calls. Lower = faster runs but more rate-limit risk; higher = slower but more reliable. The actor still adds short backoff between retries automatically. ## `timezone` (type: `string`): IANA timezone for date-range bucketing (`startDate`/`endDate`). Default UTC. ## Actor input object example ```json { "query": "shopify", "adIds": [], "region": "all", "sortBy": "last_shown_date,desc", "quickSearch": true, "maxItems": 10, "regionFilter": [], "industryFilter": [], "languageFilter": [], "ctaFilter": [], "useApifyProxy": true, "requestDelaySecs": 1, "timezone": "UTC" } ``` # 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 = { "query": "shopify", "adIds": [], "region": "all", "sortBy": "last_shown_date,desc", "quickSearch": true, "maxItems": 10, "regionFilter": [], "industryFilter": [], "languageFilter": [], "ctaFilter": [], "useApifyProxy": true, "requestDelaySecs": 1, "timezone": "UTC" }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/tiktok-ads-library-scraper-pro").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 = { "query": "shopify", "adIds": [], "region": "all", "sortBy": "last_shown_date,desc", "quickSearch": True, "maxItems": 10, "regionFilter": [], "industryFilter": [], "languageFilter": [], "ctaFilter": [], "useApifyProxy": True, "requestDelaySecs": 1, "timezone": "UTC", } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/tiktok-ads-library-scraper-pro").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 '{ "query": "shopify", "adIds": [], "region": "all", "sortBy": "last_shown_date,desc", "quickSearch": true, "maxItems": 10, "regionFilter": [], "industryFilter": [], "languageFilter": [], "ctaFilter": [], "useApifyProxy": true, "requestDelaySecs": 1, "timezone": "UTC" }' | apify call crawlerbros/tiktok-ads-library-scraper-pro --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/tiktok-ads-library-scraper-pro", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Scraper Pro", "description": "Scrape TikTok's public ad transparency library by query, advertiser, region, and date range. Pulls ad text, video URL, advertiser, impression buckets, and per-region/age/gender targeting. Pro filters: regionFilter, industryFilter, minImpressions, daysActive derived field.", "version": "1.0", "x-build-id": "llWHBu3fZqIGzY12b" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~tiktok-ads-library-scraper-pro/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-tiktok-ads-library-scraper-pro", "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/crawlerbros~tiktok-ads-library-scraper-pro/runs": { "post": { "operationId": "runs-sync-crawlerbros-tiktok-ads-library-scraper-pro", "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/crawlerbros~tiktok-ads-library-scraper-pro/run-sync": { "post": { "operationId": "run-sync-crawlerbros-tiktok-ads-library-scraper-pro", "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": { "query": { "title": "Search query", "type": "string", "description": "Free-text query — company name, domain, or ad text. Leave empty to browse all ads.", "default": "shopify" }, "adIds": { "title": "Ad IDs (direct lookup)", "type": "array", "description": "Direct list of TikTok ad IDs. Bypasses search and fetches each ad's detail page directly.", "default": [], "items": { "type": "string" } }, "advertiserName": { "title": "Advertiser name", "type": "string", "description": "Filter by advertiser name (substring match)." }, "region": { "title": "Region", "enum": [ "all", "AT", "BE", "BG", "CH", "CY", "CZ", "DE", "DK", "EE", "ES", "FI", "FR", "GB", "GR", "HR", "HU", "IE", "IS", "IT", "LI", "LT", "LU", "LV", "MT", "NL", "NO", "PL", "PT", "RO", "SE", "SI", "SK", "TR" ], "type": "string", "description": "TikTok ad region. The library covers EU/EEA + UK/CH/TR (DSA transparency). Use `all` for all-region search.", "default": "all" }, "startDate": { "title": "Start date (YYYY-MM-DD)", "type": "string", "description": "Earliest ad start date. Default: 1 year ago." }, "endDate": { "title": "End date (YYYY-MM-DD)", "type": "string", "description": "Latest ad end date. Default: today." }, "sortBy": { "title": "Sort by", "enum": [ "last_shown_date,desc", "last_shown_date,asc", "create_time,desc", "create_time,asc", "impression,desc", "impression,asc" ], "type": "string", "description": "How to sort results.", "default": "last_shown_date,desc" }, "quickSearch": { "title": "Quick search (skip detail pages)", "type": "boolean", "description": "When true, skip the ad-detail fetch and only return data from the listing card. Faster but omits some fields (full targeting breakdown).", "default": true }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Hard cap on emitted ads.", "default": 10 }, "regionFilter": { "title": "Region filter (Pro)", "type": "array", "description": "Only emit ads that target one of these regions. Case-insensitive substring match against `targetingByLocation`.", "default": [], "items": { "type": "string" } }, "minImpressions": { "title": "Min impressions (Pro)", "minimum": 0, "maximum": 1000000000, "type": "integer", "description": "Drop ads with fewer than this many impressions (numeric value parsed from TikTok's bucket like `10K-100K`)." }, "industryFilter": { "title": "Industry filter (Pro)", "type": "array", "description": "Only emit ads whose advertiser industry contains one of these substrings.", "default": [], "items": { "type": "string" } }, "languageFilter": { "title": "Language filter (Pro)", "type": "array", "description": "Only emit ads in these languages (matched case-insensitively against the `adLanguages` field, e.g. `en`, `de`, `fr`). Ads without a detected language are kept. Most effective with `quickSearch=false`.", "default": [], "items": { "type": "string" } }, "ctaFilter": { "title": "CTA filter (Pro)", "type": "array", "description": "Only emit ads whose call-to-action button text contains one of these substrings (case-insensitive — e.g. `Shop Now`, `Learn More`, `Sign Up`). Ads without a CTA are dropped. Requires `quickSearch=false` — CTA data is only available from the detail page.", "default": [], "items": { "type": "string" } }, "useApifyProxy": { "title": "Use Apify proxy", "type": "boolean", "description": "Route requests through Apify's residential proxy pool with EU exit IPs. Strongly recommended — TikTok's API aggressively rate-limits per-IP and cloud datacenter IPs hit the cap fast. The actor automatically rotates the proxy session on 'limit exceed' errors.", "default": true }, "requestDelaySecs": { "title": "Delay between requests (seconds)", "minimum": 0, "maximum": 10, "type": "integer", "description": "Pause between successive API calls. Lower = faster runs but more rate-limit risk; higher = slower but more reliable. The actor still adds short backoff between retries automatically.", "default": 1 }, "timezone": { "title": "Timezone", "enum": [ "UTC", "Europe/London", "Europe/Berlin", "Europe/Paris", "Europe/Madrid", "Europe/Rome", "Europe/Amsterdam", "Europe/Stockholm", "Europe/Warsaw", "Europe/Athens", "Europe/Istanbul", "Europe/Moscow", "Asia/Dubai", "Asia/Tokyo", "Asia/Shanghai", "Asia/Singapore", "Asia/Kolkata", "Australia/Sydney", "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", "America/Sao_Paulo", "America/Mexico_City" ], "type": "string", "description": "IANA timezone for date-range bucketing (`startDate`/`endDate`). Default UTC.", "default": "UTC" } } }, "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 } } } } } } } } } } ```