{ "openapi": "3.0.1", "info": { "title": "TikTok Top Ads Scraper", "description": "Get top-performing TikTok ads from the Creative Center 'Top Ads' dashboard. Filter by country, industry, objective, language, format, and ranking (For You / CTR / Reach). Returns ad title, brand, creative video URL, and performance metrics, with optional detail enrichment. HTTP-only, no login.", "version": "1.0", "x-build-id": "QAQl4foPuUvydVf8q" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/xtracto~tiktok-top-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-xtracto-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/xtracto~tiktok-top-ads-scraper/runs": { "post": { "operationId": "runs-sync-xtracto-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/xtracto~tiktok-top-ads-scraper/run-sync": { "post": { "operationId": "run-sync-xtracto-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": [ "country_code" ], "properties": { "country_code": { "title": "Country / Region", "type": "string", "description": "ISO-2 country code for which to fetch top ads. Required by TikTok's Creative Center backend. Examples: US, GB, ID, JP, BR, DE, FR, KR, MX, AU.", "default": "US" }, "period": { "title": "Time Period (days)", "enum": [ "7", "30", "180" ], "type": "string", "description": "Trending window in days. TikTok exposes 7, 30, and 180.", "default": "7" }, "order_by": { "title": "Sort / Rank By", "enum": [ "for_you", "ctr", "reach" ], "type": "string", "description": "How to rank the ads. 'For You' is TikTok's blended quality score, 'CTR' is click-through performance, 'Reach' is impression scale.", "default": "for_you" }, "ecom_preset": { "title": "E-commerce / GMV Preset (overrides industry + objective)", "enum": [ "off", "shop_general", "shop_beauty", "shop_apparel", "shop_food_beverage", "shop_home_garden", "shop_travel", "shop_electronics" ], "type": "string", "description": "Convenience preset that targets TikTok Shop-style ads as a GMV proxy. Selecting one of these auto-fills `industry` + `objective` for a typical DTC vertical. Leave as 'off' to use raw `industry` / `objective` values directly. (Recommended: use this preset for TikTok Shop / affiliate research; see README → 'GMV Proxy via Top Ads' for the full workflow.)", "default": "off" }, "industry": { "title": "Industry Filter (raw)", "type": "string", "description": "Filter ads by industry vertical. Leave empty for all. Examples: label_14000000000 (Food & Beverage), label_22000000000 (Apparel & Accessories), label_24000000000 (Beauty & Personal Care), label_26000000000 (Electronics). Ignored when `ecom_preset` is set.", "default": "" }, "objective": { "title": "Campaign Objective Filter (raw)", "type": "string", "description": "Filter ads by campaign objective. Leave empty for all. Examples: campaign_objective_conversion (the GMV/buying objective), campaign_objective_traffic, campaign_objective_reach. Ignored when `ecom_preset` is set.", "default": "" }, "ad_language": { "title": "Ad Language Filter", "type": "string", "description": "Filter ads by the language of the ad copy. Leave empty for all. Examples: en, id, es, pt, ja.", "default": "" }, "ad_format": { "title": "Ad Format Filter", "type": "string", "description": "Filter ads by creative format (image / video / spark / etc.). Leave empty for all.", "default": "" }, "limit": { "title": "Max Ads", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of ads to return. TikTok exposes ~100 per filter combination at the top of the dashboard.", "default": 20 }, "include_detail": { "title": "Enrich With Detail Page", "type": "boolean", "description": "When enabled, the actor calls the detail endpoint for every ad to enrich it with landing page URL, engagement counts (comment, share), keyword list, regional split, and creative pattern label. Roughly doubles run time.", "default": false }, "proxy": { "title": "Proxy configuration", "type": "object", "description": "Apify proxy configuration. Optional. Recommended for large fan-outs across countries/industries to avoid rate-limit on a single egress IP.", "default": { "useApifyProxy": false } } } }, "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 } } } } } } } } } }