{ "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 } } } } } } } } } }