{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Research Service", "description": "Research TikTok ads by product, topic, or verified competitor across 32 supported European markets.", "version": "0.1", "x-build-id": "iBbqFzo8LIeR7MvT9" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/diamade~tiktok-ads-research-service/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-diamade-tiktok-ads-research-service", "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/diamade~tiktok-ads-research-service/runs": { "post": { "operationId": "runs-sync-diamade-tiktok-ads-research-service", "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/diamade~tiktok-ads-research-service/run-sync": { "post": { "operationId": "run-sync-diamade-tiktok-ads-research-service", "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": [ "query" ], "properties": { "researchType": { "title": "What do you want to research?", "enum": [ "product_topic", "specific_competitor" ], "type": "string", "description": "Product / Topic finds ads where your subject is materially relevant. Specific Competitor safely resolves an advertiser or related brand cluster before collecting its ads." }, "query": { "title": "Product, topic, keyword, or competitor", "minLength": 1, "maxLength": 200, "type": "string", "description": "Enter the phrase exactly as you want it researched, for example running shoes, electric vehicles, or Nike. For a competitor, use the clearest brand or legal advertiser name you know. The original text is preserved in the output." }, "resultMode": { "title": "How much research do you want?", "enum": [ "preview", "full" ], "type": "string", "description": "Preview returns up to 12 real canonical rows with no result fees. Full collects the requested depth and can take longer or use more platform resources." }, "relevantOnly": { "title": "Keep only materially relevant ads (Product / Topic only)", "type": "boolean", "description": "Used only for Product / Topic. An ad is kept only when the query is a substantial subject, not a passing mention. Turn this off only when you intentionally want broader source-defined matches. Specific Competitor uses verified advertiser membership instead and ignores this switch." }, "countryMode": { "title": "Market coverage", "enum": [ "ALL_SUPPORTED_COUNTRIES", "EXPLICIT_COUNTRY_SET" ], "type": "string", "description": "All supported countries searches the current 32-market launch set. Selected countries is faster and easier to estimate for a first Full run." }, "countries": { "title": "Selected countries", "maxItems": 32, "uniqueItems": true, "type": "array", "description": "Used only with Selected countries. Leave this empty when All 32 supported countries is selected.", "items": { "type": "string", "enum": [ "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IE", "IT", "LV", "LT", "LU", "MT", "NL", "PL", "PT", "RO", "SK", "SI", "ES", "SE", "NO", "IS", "LI", "GB", "CH" ], "enumTitles": [ "🇦🇹 Österreich", "🇧🇪 België / Belgique", "🇧🇬 България", "🇭🇷 Hrvatska", "🇨🇾 Κύπρος", "🇨🇿 Česko", "🇩🇰 Danmark", "🇪🇪 Eesti", "🇫🇮 Suomi", "🇫🇷 France", "🇩🇪 Deutschland", "🇬🇷 Ελλάδα", "🇭🇺 Magyarország", "🇮🇪 Ireland", "🇮🇹 Italia", "🇱🇻 Latvija", "🇱🇹 Lietuva", "🇱🇺 Luxembourg", "🇲🇹 Malta", "🇳🇱 Nederland", "🇵🇱 Polska", "🇵🇹 Portugal", "🇷🇴 România", "🇸🇰 Slovensko", "🇸🇮 Slovenija", "🇪🇸 España", "🇸🇪 Sverige", "🇳🇴 Norge", "🇮🇸 Ísland", "🇱🇮 Liechtenstein", "🇬🇧 United Kingdom", "🇨🇭 Schweiz / Suisse" ] } }, "maxResults": { "title": "Maximum results per country", "minimum": 1, "type": "integer", "description": "Full mode only. A number applies separately to each country. Leave empty for all source-available results in the date range; this may take substantially longer and use more platform resources. Preview always uses one global 12-row cap." }, "fromDate": { "title": "From date", "type": "string", "description": "Optional. Type DDMMYYYY, DD.MM.YYYY, DD/MM/YYYY, or YYYY-MM-DD. Leave empty to use all history the public source makes available (not a guarantee of archive completeness)." }, "toDate": { "title": "To date", "type": "string", "description": "Optional and inclusive. Use the same date formats, or type recent, now, or today. Leave empty for the current run time." }, "detail": { "title": "Add per-ad Detail", "type": "boolean", "description": "Optional value layer, OFF by default. Successful Detail adds destination, CTA, campaign goal, targeting, and media information to the same ad row. If Detail is unavailable, the valid base row remains and the status explains why." }, "advertiserReport": { "title": "Add Advertiser Report", "type": "boolean", "description": "Specific Competitor only, OFF by default. Adds a country-scoped advertiser report. Results from successful countries remain available if another country has no data or a temporary source problem." }, "competitorClusterId": { "title": "Verified competitor selection ID", "type": "string", "description": "Advanced. Use only when a previous Specific Competitor run found unrelated advertisers and asked you to choose. Paste the returned verified cluster ID here, then rerun the same competitor query." } } }, "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 } } } } } } } } } }