{ "openapi": "3.0.1", "info": { "title": "TikTok Ad Intelligence", "description": "Rank a competitor's TikTok ads by how long they have run and how widely they were duplicated, and get a summary per advertiser.", "version": "1.0", "x-build-id": "vte2azXR11NvdS5o0" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/getdataforu~tiktok-ad-intelligence/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-getdataforu-tiktok-ad-intelligence", "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/getdataforu~tiktok-ad-intelligence/runs": { "post": { "operationId": "runs-sync-getdataforu-tiktok-ad-intelligence", "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/getdataforu~tiktok-ad-intelligence/run-sync": { "post": { "operationId": "run-sync-getdataforu-tiktok-ad-intelligence", "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": [ "advertisers" ], "properties": { "advertisers": { "title": "Advertisers or keywords", "minItems": 1, "type": "array", "description": "Competitor names (ideally the legal entity name as it appears in the ad library, e.g. \"JD SPORTS FASHION PLC\") or keywords describing your category.", "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "Which ad libraries to analyse. TikTok publishes this data for the EEA, the UK, Switzerland and Turkey only.", "items": { "type": "string", "enum": [ "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" ], "enumTitles": [ "Austria", "Belgium", "Bulgaria", "Switzerland", "Cyprus", "Czech Republic", "Germany", "Denmark", "Estonia", "Spain", "Finland", "France", "United Kingdom", "Greece", "Croatia", "Hungary", "Ireland", "Iceland", "Italy", "Liechtenstein", "Lithuania", "Luxembourg", "Latvia", "Malta", "Netherlands", "Norway", "Poland", "Portugal", "Romania", "Sweden", "Slovenia", "Slovakia", "Turkey" ] }, "default": [ "GB" ] }, "lastDays": { "title": "Last N days", "minimum": 7, "maximum": 365, "type": "integer", "description": "How far back to analyse. 30 days is a good default; shorter windows make flight lengths look artificially short.", "default": 30 }, "dateFrom": { "title": "Date from", "type": "string", "description": "Optional exact start of the range, as YYYY-MM-DD. Overrides \"Last N days\"." }, "dateTo": { "title": "Date to", "type": "string", "description": "Optional exact end of the range, as YYYY-MM-DD. Defaults to today." }, "includeTargeting": { "title": "Include audience targeting", "type": "boolean", "description": "Adds the age, gender and interest breakdown to each ad and to the advertiser summary. It costs one extra request per ad and TikTok refuses roughly half of those from shared proxy IPs, so leave it off for a first look at who is winning, and turn it on once you know which advertisers matter.", "default": false }, "maxAdsPerAdvertiser": { "title": "Maximum ads per advertiser", "minimum": 10, "maximum": 5000, "type": "integer", "description": "How many ads to analyse per advertiser, per country. More ads make the summary more reliable and the run longer - roughly 100 ads per advertiser every four minutes. Advertisers are processed side by side.", "default": 100 }, "topCreatives": { "title": "Top creatives per advertiser", "minimum": 1, "maximum": 25, "type": "integer", "description": "How many winning ads to embed in each advertiser summary row.", "default": 5 }, "maxRequestRetries": { "title": "Retries per request", "minimum": 1, "maximum": 15, "type": "integer", "description": "How many times to retry a request that TikTok answers with \"system busy\", each time from a fresh proxy IP.", "default": 6 }, "sessionCount": { "title": "Parallel sessions", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many independent sessions (each on its own IP) fetch targeting data at the same time. Higher is faster; lower is gentler on TikTok and on your proxy bill.", "default": 5 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "TikTok rate-limits single IP addresses aggressively. Residential proxies are strongly recommended and used by default.", "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }