{ "openapi": "3.0.1", "info": { "title": "TikTok Ad Intelligence & Creative Watcher", "description": "Scrape TikTok Creative Center Top Ads by market and date window, and see which creatives are new or changed on every run. Flat, agent-ready records with advertiser, ad copy, video and image URLs. Optional AI read of hook, audience, offer, funnel stage and one A/B test.", "version": "0.0", "x-build-id": "bKuRc5tsTdvFptJLw" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/marielise.dev~tiktok-creative-watch/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-marielise.dev-tiktok-creative-watch", "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/marielise.dev~tiktok-creative-watch/runs": { "post": { "operationId": "runs-sync-marielise.dev-tiktok-creative-watch", "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/marielise.dev~tiktok-creative-watch/run-sync": { "post": { "operationId": "run-sync-marielise.dev-tiktok-creative-watch", "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", "properties": { "countries": { "title": "Markets", "maxItems": 3, "type": "array", "description": "Two-letter ISO country codes of the TikTok markets to collect, for example US, GB, DE. Each market is a separate fetch billed as one monitored source and takes 60-90 seconds, so at most 3 fit inside the default 300-second run timeout. Leave empty for TikTok's global Top Ads page.", "items": { "type": "string" }, "default": [] }, "period": { "title": "Date window", "enum": [ "7", "30", "180" ], "type": "string", "description": "How far back TikTok should rank Top Ads. TikTok supports 7, 30 and 180 days only; any other value falls back to 30.", "default": "30" }, "maxAdsPerSearch": { "title": "Maximum ads per market", "minimum": 1, "maximum": 500, "type": "integer", "description": "Safety cap on creatives returned per market. TikTok serves 20 ads per Top Ads page and does not paginate for anonymous access, so values above 20 only matter when several markets or windows are combined.", "default": 20 }, "watchMode": { "title": "Track changes between runs", "type": "boolean", "description": "Store a compact fingerprint per creative and label every record on later runs as new, changed or unchanged. Turn off for a one-off snapshot, where every record is labelled untracked.", "default": true }, "includeUnchanged": { "title": "Include unchanged ads", "type": "boolean", "description": "Return creatives already seen with no change, labelled unchanged. Leave on for a full history. Turn off for an alerts-only dataset containing new and changed creatives only.", "default": true }, "analyzeCreative": { "title": "AI creative analysis", "type": "boolean", "description": "Add an AI read of each new or changed creative: hook, target audience, offer, funnel stage, creative format and one concrete A/B test. Billed per insight and never billed for an unchanged creative. Off by default so plain collection stays cheap.", "default": false }, "searchUrls": { "title": "Creative Center URLs (advanced)", "type": "array", "description": "Optional override. Paste full TikTok Creative Center Top Ads URLs to target industry filters or anything the fields above do not express. When set, these URLs are used in addition to the markets above, and each URL is billed as one monitored source.", "items": { "type": "string" }, "default": [] }, "proxy": { "title": "Proxy configuration", "type": "object", "description": "Residential proxy is the reliable configuration for TikTok Creative Center and is the default. Datacenter proxy is cheaper but is blocked more often.", "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 } } } } } } } } } }