# TikTok Top Ads Scraper & Creative Analyzer (`thenetaji/tiktok-top-ads-scraper`) Actor Find high-performing public TikTok ads in Creative Center. Search ranked ads, browse TikTok's Spotlight picks, or analyze known ads by URL or ID. Export videos and engagement metrics, then optionally add details, per-second performance, benchmarks, and similar creatives. - **URL**: https://apify.com/thenetaji/tiktok-top-ads-scraper.md - **Developed by:** [The Netaji](https://apify.com/thenetaji) (community) - **Categories:** Social media, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.60 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 **Discover winning TikTok creatives, inspect their performance shape, and move from inspiration to a reusable creative dataset.** Top Ads becomes useful when ranking, creative detail, and video analysis live in one workflow. I combined those steps here so a discovery run can stay lightweight while a focused analysis run can go much deeper. ### Choose discovery, Spotlight, or analysis Ranked mode explores creatives by market and performance signal. Spotlight mode follows TikTok's curated selection. Analyze mode starts from known material IDs or a copied Top Ad URL and can branch one hop into related creatives. #### Discover ranked creatives Rank Top Ads by market, period, performance signal, industry, objective, format, language, or keyword. | Field | Type | Required | Description | | --- | --- | --- | --- | | `scraperType` | string | Yes | Choose Ranked to search high-performing ads with filters, Spotlight to browse TikTok's curated examples, or Analyze to inspect ads you already know by URL or material ID. | | `country_codes` | array | No | Markets to search in Ranked mode and to use when finding similar creatives in Analyze mode. Spotlight ignores this field. | | `period` | string | No | In Ranked mode, compare ads shown during the last 7, 30, or 180 days. | | `top_ads_sort` | string | No | In Ranked mode, order ads by TikTok's recommendations or by reach, click-through rate, video-view rate, conversion rate, or likes. | | `industry_ids` | string | No | Optional comma-separated Creative Center industry IDs for Ranked mode. The easiest way to use these is to paste a filtered Top Ads dashboard URL instead. | | `objective_ids` | string | No | Optional comma-separated campaign-objective IDs for Ranked mode, such as 1 for Traffic or 3 for Conversions. A filtered dashboard URL can supply them. | | `ad_format` | string | No | In Ranked mode, return Spark Ads, non-Spark Ads, or both when left empty. | | `likes_percentile` | string | No | In Ranked mode, keep one likes-ranking group. Top 1–20% contains the most-liked ads. | | `ad_language` | string | No | Optional language spoken or written in ranked ads, such as en, fr, or de. This filters creatives; it does not change the Actor interface language. | | `keyword` | string | No | Brand, product, or topic to search in Ranked mode. Spotlight and Analyze modes ignore it. | | `maxItems` | integer | No | Maximum number of primary ads to save. Set 0 to continue until no more pages remain. | #### Browse Spotlight Collect TikTok Creative Center's curated Spotlight creatives. | Field | Type | Required | Description | | --- | --- | --- | --- | | `scraperType` | string | Yes | Choose Ranked to search high-performing ads with filters, Spotlight to browse TikTok's curated examples, or Analyze to inspect ads you already know by URL or material ID. | | `startUrl` | string | No | Optional shortcut: paste a public Creative Center Top Ads dashboard, Top Ad detail, or Spotlight URL. URL values select the matching workflow and explicit fields override matching URL filters. | | `maxItems` | integer | No | Maximum number of primary ads to save. Set 0 to continue until no more pages remain. | #### Analyze known creatives Use material IDs or a Top Ad URL, then optionally add timelines, benchmarks, and one-hop related creatives. | Field | Type | Required | Description | | --- | --- | --- | --- | | `scraperType` | string | Yes | Choose Ranked to search high-performing ads with filters, Spotlight to browse TikTok's curated examples, or Analyze to inspect ads you already know by URL or material ID. | | `material_ids` | array | No | Ads to inspect in Analyze mode. Enter the numeric ID shown in a Creative Center Top Ad URL after /topads/, or paste the full URL above instead. | | `startUrl` | string | No | Optional shortcut: paste a public Creative Center Top Ads dashboard, Top Ad detail, or Spotlight URL. URL values select the matching workflow and explicit fields override matching URL filters. | | `includeVideoTimeline` | boolean | No | For every eligible video, fetch how the selected metric changes second by second and identify highlighted moments. Each successful timeline request has an enrichment charge. | | `timelineMetric` | string | No | Choose the signal plotted across the video: click-through rate (CTR), conversion rate (CVR), clicks, conversions, or viewer retention. | | `includePercentile` | boolean | No | Compare every eligible ad with other Top Ads for the selected metric and period. Each successful benchmark request has an enrichment charge. | | `percentileMetric` | string | No | Choose the signal used to compare this ad with other Top Ads: CTR, CVR, clicks, conversions, or viewer retention. | | `percentilePeriod` | string | No | Choose whether the benchmark compares performance from the last 7, 30, or 180 days. | | `includeRelatedAds` | boolean | No | Only in Analyze mode: save similar Top Ads for each ad you inspect. The Actor performs one recommendation request per input ad and does not recursively expand the recommendations. | | `maxRelatedItems` | integer | No | Maximum number of similar ads to save for each input ad in Analyze mode. | #### Example CTR-ranked scan ```json { "scraperType": "topRanked", "country_codes": [ "US" ], "period": "30", "top_ads_sort": "ctr", "maxItems": 20, "enrichTopAdDetails": false } ```` ### Creative fields plus optional performance depth Every result identifies the material, brand, caption, market, engagement, video, and destination when available. Detail, per-second timeline, percentile, and related-creative options are explicit so the dataset reflects exactly what the run requested. #### 📦 Creative identity | Field | Type | Description | | --- | --- | --- | | `material_id` | string | Unique Creative Center Top Ad material ID. | | `brand_name` | string | Brand name reported by Creative Center. | | `ad_title` | string | Top Ad caption or title. | | `countries` | array | Countries associated with the Top Ad. | | `creative_center_url` | string | Public Creative Center page for the material. | #### 📊 Performance | Field | Type | Description | | --- | --- | --- | | `likes` | number | Likes reported for the Top Ad. | | `comments` | number | Comments reported for the Top Ad. | | `shares` | number | Shares reported for the Top Ad. | | `ctr` | number | CTR value reported by Creative Center. | | `budget_level` | number | Creative Center budget bucket. | #### 🎬 Video and destination | Field | Type | Description | | --- | --- | --- | | `video_url` | string | Highest-resolution video URL exposed for the Top Ad. | | `cover_url` | string | Top Ad video cover image. | | `video_duration` | number | Top Ad video duration in seconds. | | `landing_page` | string | Landing page associated with the Top Ad. | #### 🔬 Analysis | Field | Type | Description | | --- | --- | --- | | `discovery_mode` | string | Workflow that discovered the Top Ad. | | `related_to_material_id` | string | Seed material ID for a related creative. | | `performance_timeline` | object | Per-second performance analysis and highlighted moments. | | `percentile_benchmark` | object | Selected metric percentile benchmark. | | `details` | object | Full detail payload, present only when the workflow fetches it. | #### Shortened creative record ```json { "material_id": "7182310470102122497", "brand_name": "Example Brand", "ad_title": "See why this creative performs", "countries": [ "US" ], "discovery_mode": "ranked", "likes": 33506, "ctr": 0.19 } ``` ### A useful creative-analysis sequence - Rank a market with enrichment disabled. - Shortlist material IDs based on the metric relevant to the campaign. - Analyze the shortlist with video timeline and percentile options. - Use related creatives to inspect one nearby cluster without uncontrolled crawling. ### Pay for results, then only the analysis you enable This Actor uses Apify pay-per-event pricing. Dataset results are the primary charge. Optional enrichment is charged only after the requested extra data is returned successfully; disabled enrichments make no add-on calls. Apify's free credits may cover small validation runs within the free usage allowance shown on the Actor pricing tab. Start with a low Max results value and leave enrichment off until the discovery query returns the creatives you want. ### Public Creative Center data and responsible use This Actor collects public advertising transparency and Creative Center data. It does not access private TikTok accounts or private user data. You are responsible for complying with applicable privacy laws, advertising rules, TikTok terms, and the rights of people or organizations represented in your results. Consult a qualified lawyer if you are unsure. ### Run from code #### Python ```python from apify_client import ApifyClient client = ApifyClient("YOUR_APIFY_API_TOKEN") run = client.actor("thenetaji/tiktok-top-ads-scraper").call(run_input={ "scraperType": "topRanked", "country_codes": [ "US" ], "period": "30", "top_ads_sort": "ctr", "maxItems": 20, "enrichTopAdDetails": false }) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) ``` #### Node.js ```javascript import { ApifyClient } from "apify-client"; const client = new ApifyClient({ token: "YOUR_APIFY_API_TOKEN" }); const run = await client.actor("thenetaji/tiktok-top-ads-scraper").call({ "scraperType": "topRanked", "country_codes": [ "US" ], "period": "30", "top_ads_sort": "ctr", "maxItems": 20, "enrichTopAdDetails": false }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` ### Pair creative and transparency research - [TikTok Ads Library Scraper](https://apify.com/thenetaji/tiktok-ads-library-scraper) — Find public TikTok ads from brands and competitors. Search by keyword or advertiser, choose a country and date range, and export ad text, delivery dates, audience estimates, impressions, and creative URLs. Optionally add targeting details or an advertiser activity report. - [Facebook Ads Library Scrape](https://apify.com/thenetaji/meta-facebook-ads-scraper) — Scrape public Facebook and Instagram ads from Meta Ad Library: search by keyword or Ad Library URL, browse every ad from a known advertiser Page, or find a Page's ID by brand name. Filter by country, status, category, format, platform, and date, and optionally enrich each ad with full details. ### Ask me about a run Use the Issues tab on the Actor page to report a failing public URL, missing field, or workflow request. Include the run ID and a redacted example input. # Actor input Schema ## `scraperType` (type: `string`): Choose Ranked to search high-performing ads with filters, Spotlight to browse TikTok's curated examples, or Analyze to inspect ads you already know by URL or material ID. ## `startUrl` (type: `string`): Optional shortcut: paste a public Creative Center Top Ads dashboard, Top Ad detail, or Spotlight URL. URL values select the matching workflow and explicit fields override matching URL filters. ## `keyword` (type: `string`): Brand, product, or topic to search in Ranked mode. Spotlight and Analyze modes ignore it. ## `material_ids` (type: `array`): Ads to inspect in Analyze mode. Enter the numeric ID shown in a Creative Center Top Ad URL after /topads/, or paste the full URL above instead. ## `maxItems` (type: `integer`): Maximum number of primary ads to save. Set 0 to continue until no more pages remain. ## `enrichTopAdDetails` (type: `boolean`): In Ranked and Spotlight modes, make one extra request per saved ad for its caption, brand, markets, industry, objectives, engagement, landing page, and creative metadata. Analyze already includes these details. ## `includeVideoTimeline` (type: `boolean`): For every eligible video, fetch how the selected metric changes second by second and identify highlighted moments. Each successful timeline request has an enrichment charge. ## `timelineMetric` (type: `string`): Choose the signal plotted across the video: click-through rate (CTR), conversion rate (CVR), clicks, conversions, or viewer retention. ## `includePercentile` (type: `boolean`): Compare every eligible ad with other Top Ads for the selected metric and period. Each successful benchmark request has an enrichment charge. ## `percentileMetric` (type: `string`): Choose the signal used to compare this ad with other Top Ads: CTR, CVR, clicks, conversions, or viewer retention. ## `percentilePeriod` (type: `string`): Choose whether the benchmark compares performance from the last 7, 30, or 180 days. ## `includeRelatedAds` (type: `boolean`): Only in Analyze mode: save similar Top Ads for each ad you inspect. The Actor performs one recommendation request per input ad and does not recursively expand the recommendations. ## `maxRelatedItems` (type: `integer`): Maximum number of similar ads to save for each input ad in Analyze mode. ## `country_codes` (type: `array`): Markets to search in Ranked mode and to use when finding similar creatives in Analyze mode. Spotlight ignores this field. ## `period` (type: `string`): In Ranked mode, compare ads shown during the last 7, 30, or 180 days. ## `top_ads_sort` (type: `string`): In Ranked mode, order ads by TikTok's recommendations or by reach, click-through rate, video-view rate, conversion rate, or likes. ## `industry_ids` (type: `string`): Optional comma-separated Creative Center industry IDs for Ranked mode. The easiest way to use these is to paste a filtered Top Ads dashboard URL instead. ## `objective_ids` (type: `string`): Optional comma-separated campaign-objective IDs for Ranked mode, such as 1 for Traffic or 3 for Conversions. A filtered dashboard URL can supply them. ## `ad_format` (type: `string`): In Ranked mode, return Spark Ads, non-Spark Ads, or both when left empty. ## `likes_percentile` (type: `string`): In Ranked mode, keep one likes-ranking group. Top 1–20% contains the most-liked ads. ## `ad_language` (type: `string`): Optional language spoken or written in ranked ads, such as en, fr, or de. This filters creatives; it does not change the Actor interface language. ## Actor input object example ```json { "scraperType": "topRanked", "startUrl": "https://ads.tiktok.com/business/creativecenter/topads/7631262985109602311/pc/en", "keyword": "skincare", "material_ids": [ "7182310470102122497" ], "maxItems": 10, "enrichTopAdDetails": false, "includeVideoTimeline": false, "timelineMetric": "retain_ctr", "includePercentile": false, "percentileMetric": "retain_ctr", "percentilePeriod": "180", "includeRelatedAds": false, "maxRelatedItems": 5, "country_codes": [ "US" ], "period": "30", "top_ads_sort": "for_you", "industry_ids": "14103000000,14104000000", "objective_ids": "1,3", "ad_language": "en" } ``` # Actor output Schema ## `dataset` (type: `string`): Dataset containing all scraped data # 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 = { "keyword": "skincare", "material_ids": [ "7631262985109602311" ], "maxItems": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("thenetaji/tiktok-top-ads-scraper").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 = { "keyword": "skincare", "material_ids": ["7631262985109602311"], "maxItems": 10, } # Run the Actor and wait for it to finish run = client.actor("thenetaji/tiktok-top-ads-scraper").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 '{ "keyword": "skincare", "material_ids": [ "7631262985109602311" ], "maxItems": 10 }' | apify call thenetaji/tiktok-top-ads-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=thenetaji/tiktok-top-ads-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Top Ads Scraper & Creative Analyzer", "description": "Find high-performing public TikTok ads in Creative Center. Search ranked ads, browse TikTok's Spotlight picks, or analyze known ads by URL or ID. Export videos and engagement metrics, then optionally add details, per-second performance, benchmarks, and similar creatives.", "version": "0.1", "x-build-id": "vWsYQJjkglEreZusU" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/thenetaji~tiktok-top-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-thenetaji-tiktok-top-ads-scraper", "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/thenetaji~tiktok-top-ads-scraper/runs": { "post": { "operationId": "runs-sync-thenetaji-tiktok-top-ads-scraper", "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/thenetaji~tiktok-top-ads-scraper/run-sync": { "post": { "operationId": "run-sync-thenetaji-tiktok-top-ads-scraper", "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", "required": [ "scraperType" ], "properties": { "scraperType": { "title": "Workflow", "enum": [ "topRanked", "topSpotlight", "topAnalyze" ], "type": "string", "description": "Choose Ranked to search high-performing ads with filters, Spotlight to browse TikTok's curated examples, or Analyze to inspect ads you already know by URL or material ID.", "default": "topRanked" }, "startUrl": { "title": "TikTok Top Ads URL", "type": "string", "description": "Optional shortcut: paste a public Creative Center Top Ads dashboard, Top Ad detail, or Spotlight URL. URL values select the matching workflow and explicit fields override matching URL filters." }, "keyword": { "title": "Brand or product keyword", "type": "string", "description": "Brand, product, or topic to search in Ranked mode. Spotlight and Analyze modes ignore it.", "default": "skincare" }, "material_ids": { "title": "Top Ad material IDs", "type": "array", "description": "Ads to inspect in Analyze mode. Enter the numeric ID shown in a Creative Center Top Ad URL after /topads/, or paste the full URL above instead.", "items": { "type": "string", "pattern": "^\\d+$" } }, "maxItems": { "title": "Max results", "minimum": 0, "type": "integer", "description": "Maximum number of primary ads to save. Set 0 to continue until no more pages remain.", "default": 10 }, "enrichTopAdDetails": { "title": "Add full details to discovered ads", "type": "boolean", "description": "In Ranked and Spotlight modes, make one extra request per saved ad for its caption, brand, markets, industry, objectives, engagement, landing page, and creative metadata. Analyze already includes these details.", "default": false }, "includeVideoTimeline": { "title": "Add per-second video performance", "type": "boolean", "description": "For every eligible video, fetch how the selected metric changes second by second and identify highlighted moments. Each successful timeline request has an enrichment charge.", "default": false }, "timelineMetric": { "title": "Timeline metric", "enum": [ "retain_ctr", "retain_cvr", "click_cnt", "convert_cnt", "play_retain_cnt" ], "type": "string", "description": "Choose the signal plotted across the video: click-through rate (CTR), conversion rate (CVR), clicks, conversions, or viewer retention.", "default": "retain_ctr" }, "includePercentile": { "title": "Add performance benchmark", "type": "boolean", "description": "Compare every eligible ad with other Top Ads for the selected metric and period. Each successful benchmark request has an enrichment charge.", "default": false }, "percentileMetric": { "title": "Percentile metric", "enum": [ "retain_ctr", "retain_cvr", "click_cnt", "convert_cnt", "play_retain_cnt" ], "type": "string", "description": "Choose the signal used to compare this ad with other Top Ads: CTR, CVR, clicks, conversions, or viewer retention.", "default": "retain_ctr" }, "percentilePeriod": { "title": "Percentile period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Choose whether the benchmark compares performance from the last 7, 30, or 180 days.", "default": "180" }, "includeRelatedAds": { "title": "Find similar creatives", "type": "boolean", "description": "Only in Analyze mode: save similar Top Ads for each ad you inspect. The Actor performs one recommendation request per input ad and does not recursively expand the recommendations.", "default": false }, "maxRelatedItems": { "title": "Max related creatives", "minimum": 1, "maximum": 20, "type": "integer", "description": "Maximum number of similar ads to save for each input ad in Analyze mode.", "default": 5 }, "country_codes": { "title": "Countries", "type": "array", "description": "Markets to search in Ranked mode and to use when finding similar creatives in Analyze mode. Spotlight ignores this field.", "items": { "type": "string", "enum": [ "ALL", "AR", "AU", "BR", "CA", "CO", "DE", "ES", "FR", "GB", "ID", "IT", "JP", "KR", "MX", "MY", "NL", "PH", "PK", "RO", "SA", "SE", "SG", "TH", "TR", "US", "VN", "ZA" ], "enumTitles": [ "All countries", "Argentina", "Australia", "Brazil", "Canada", "Colombia", "Germany", "Spain", "France", "United Kingdom", "Indonesia", "Italy", "Japan", "South Korea", "Mexico", "Malaysia", "Netherlands", "Philippines", "Pakistan", "Romania", "Saudi Arabia", "Sweden", "Singapore", "Thailand", "Turkey", "United States", "Vietnam", "South Africa" ] }, "default": [ "US" ] }, "period": { "title": "Ranking period", "enum": [ "7", "30", "180" ], "type": "string", "description": "In Ranked mode, compare ads shown during the last 7, 30, or 180 days.", "default": "30" }, "top_ads_sort": { "title": "Rank by", "enum": [ "for_you", "reach", "ctr", "two_second_view_rate", "six_second_view_rate", "cvr", "likes" ], "type": "string", "description": "In Ranked mode, order ads by TikTok's recommendations or by reach, click-through rate, video-view rate, conversion rate, or likes.", "default": "for_you" }, "industry_ids": { "title": "Industry IDs", "type": "string", "description": "Optional comma-separated Creative Center industry IDs for Ranked mode. The easiest way to use these is to paste a filtered Top Ads dashboard URL instead." }, "objective_ids": { "title": "Objective IDs", "type": "string", "description": "Optional comma-separated campaign-objective IDs for Ranked mode, such as 1 for Traffic or 3 for Conversions. A filtered dashboard URL can supply them." }, "ad_format": { "title": "Ad format", "enum": [ "spark", "non_spark" ], "type": "string", "description": "In Ranked mode, return Spark Ads, non-Spark Ads, or both when left empty." }, "likes_percentile": { "title": "Likes percentile", "enum": [ "top_1_20", "top_21_40", "top_41_60", "top_61_80", "top_81_100" ], "type": "string", "description": "In Ranked mode, keep one likes-ranking group. Top 1–20% contains the most-liked ads." }, "ad_language": { "title": "Ad language", "type": "string", "description": "Optional language spoken or written in ranked ads, such as en, fr, or de. This filters creatives; it does not change the Actor interface language." } } }, "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 } } } } } } } } } } ```