{ "openapi": "3.0.1", "info": { "title": "TikTok Creative Center Top Ads Insights", "description": "TikTok Creative Center Top Ads Insights analyzes trending TikTok videos, capturing metrics like views, likes, shares, comments, creators, hashtags, sounds, and growth patterns. Ideal for trend tracking, content research, campaign planning, and automating TikTok performance insights at scale.", "version": "0.1", "x-build-id": "sbSEAWkN1LFRRsOvQ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/simpleapi~tiktok-trending-videos-insights/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-simpleapi-tiktok-trending-videos-insights", "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/simpleapi~tiktok-trending-videos-insights/runs": { "post": { "operationId": "runs-sync-simpleapi-tiktok-trending-videos-insights", "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/simpleapi~tiktok-trending-videos-insights/run-sync": { "post": { "operationId": "run-sync-simpleapi-tiktok-trending-videos-insights", "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": [ "countryCodes" ], "properties": { "countryCodes": { "title": "🌐 Country Codes", "type": "array", "description": "One or more two-letter country codes (e.g. 'US', 'GB', 'AU', 'CA', 'DE'). The anonymous Creative Center tier serves ~40 ads per country, so adding more countries is the main way to get more rows per run (they reuse one signed session).", "default": [ "US" ], "items": { "type": "string" } }, "sortOrder": { "title": "↕️ Sort Order", "enum": [ "for_you", "ctr" ], "type": "string", "description": "How to order the Top Ads feed. Only two orderings are honored by the endpoint: 'For You' (the default trending feed) and 'CTR' (click-through rate). The old 5-way sort was cosmetic.", "default": "for_you" }, "period": { "title": "📅 Time Window", "enum": [ "7", "30", "180" ], "type": "string", "description": "Trailing time window for Top Ads. Only 7 / 30 / 180 days are accepted by the endpoint (any other value is snapped to the nearest).", "default": "7" }, "maxItems": { "title": "🔢 Max Ads per Country", "minimum": 0, "maximum": 200, "type": "integer", "description": "Maximum Top Ads to collect per country. NOTE: the anonymous Creative Center tier realistically returns only ~40 per (country, period). Use multiple countryCodes to get more rows. 0 = no limit (still bounded by the ~40 ceiling).", "default": 40 }, "includeDetails": { "title": "🔎 Include Ad Detail Enrichment", "type": "boolean", "description": "Opt-in: for each ad, call the top_ads/v2/detail endpoint to add comment count, share count, landing_page (lead-gen URL) and the country list the ad ran in. Slower and billed as a separate 'detail_result' event per enriched ad.", "default": false }, "keyword": { "title": "🔍 Keyword (endpoint search)", "type": "string", "description": "Passed to the Top Ads endpoint as a server-side search term (matches ad text). Leave empty for no keyword search." }, "industry": { "title": "🏭 Industry (endpoint param)", "type": "string", "description": "Optional Creative Center industry filter passed straight to the endpoint (e.g. an industry key/id). Leave empty for all industries." }, "objective": { "title": "🎯 Objective (endpoint param)", "type": "string", "description": "Optional Creative Center advertising-objective filter passed to the endpoint (e.g. 'traffic', 'conversions', 'app_install'). Leave empty for all objectives." }, "adLanguage": { "title": "🈳 Ad Language (endpoint param)", "type": "string", "description": "Optional language filter for ad creatives passed to the endpoint (e.g. 'en'). Leave empty for all languages." }, "adFormat": { "title": "🎬 Ad Format (endpoint param)", "type": "string", "description": "Optional ad-format filter passed to the endpoint. Leave empty for all formats." }, "minLikes": { "title": "👍 Minimum Likes", "minimum": 0, "type": "integer", "description": "Client-side filter: drop ads with fewer likes than this. 0 = no minimum.", "default": 0 }, "minCtr": { "title": "📈 Minimum CTR", "type": "number", "description": "Client-side filter: drop ads whose CTR is below this value (same scale the endpoint returns). Leave empty for no minimum." }, "minDuration": { "title": "⏱️ Minimum Duration (seconds)", "minimum": 0, "type": "integer", "description": "Client-side filter: drop ads shorter than this many seconds. Leave empty for no minimum." }, "maxDuration": { "title": "⏱️ Maximum Duration (seconds)", "minimum": 0, "type": "integer", "description": "Client-side filter: drop ads longer than this many seconds. Leave empty for no maximum." }, "keywords": { "title": "🔍 Include Keywords (client-side)", "type": "array", "description": "Client-side: keep only ads whose ad text contains at least one of these words (case-insensitive).", "items": { "type": "string" } }, "excludeKeywords": { "title": "🚫 Exclude Keywords (client-side)", "type": "array", "description": "Client-side: drop ads whose ad text contains any of these words (case-insensitive).", "items": { "type": "string" } }, "proxyConfiguration": { "title": "🌐 Proxy Configuration", "type": "object", "description": "TikTok Creative Center blocks datacenter IPs — RESIDENTIAL proxy is required to capture the signed session. Defaults to Apify residential.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } }