{ "openapi": "3.0.1", "info": { "title": "TikTok Creative Center Scraper — top ads by market & period", "description": "Scrape TikTok Creative Center top ads into clean JSON: CTR, likes, video, industry, landing page. Batch jobs, honest run summaries.", "version": "0.1", "x-build-id": "kRApgf9UICYOYL63z" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/t2solutions~tiktok-creative-center-ads-fetch/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-t2solutions-tiktok-creative-center-ads-fetch", "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/t2solutions~tiktok-creative-center-ads-fetch/runs": { "post": { "operationId": "runs-sync-t2solutions-tiktok-creative-center-ads-fetch", "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/t2solutions~tiktok-creative-center-ads-fetch/run-sync": { "post": { "operationId": "run-sync-t2solutions-tiktok-creative-center-ads-fetch", "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": [ "jobs" ], "properties": { "jobs": { "title": "Jobs", "minItems": 1, "maxItems": 50, "type": "array", "description": "One or more top-ads filter-set jobs (1-50). Each job fetches TikTok Creative Center top ads for one country x period x sort, optionally narrowed by industry / objective / language id. Every job shares one fail-safe deadline and one run-level RUN_SUMMARY row. v1 supports type \"topAds\" only - there is deliberately no keyword, proxy, token or credential field (plain-HTTP no-login access is a hard constraint).", "items": { "type": "object", "properties": { "type": { "title": "Type", "type": "string", "enum": [ "topAds" ], "default": "topAds", "description": "Job type. v1 supports \"topAds\" only; any other value fails that job with a recorded reason." }, "label": { "title": "Label", "type": "string", "description": "Your name for this job - echoed as jobLabel on every row and in RUN_SUMMARY. Default: job-N." }, "country": { "title": "Country", "type": "string", "default": "US", "description": "ISO-3166 alpha-2 country code, validated against the live Creative Center filters vocabulary (28 countries observed 2026-10-25). An unknown code fails this job with a recorded reason - never a silent empty result. Default: US." }, "period": { "title": "Period (days)", "type": "integer", "minimum": 7, "maximum": 180, "default": 30, "description": "Upstream day window for the top-ads list. Allowed values are exactly 7, 30 or 180 (the platform schema cannot express an integer enum, so the closed set is enforced at run time: any other value fails the job with recorded reason invalid_period - never a silent surprise). Default: 30." }, "sortBy": { "title": "Sort by", "type": "string", "enum": [ "for_you", "likes", "ctr", "impressions", "watch_2s_rate", "watch_6s_rate", "conversion_rate" ], "default": "for_you", "description": "Ranking order of the list (mapped to the upstream order_by values). Default: for_you. With exhaust=true this sort is the first of the seven rotations." }, "industry": { "title": "Industry id (optional)", "type": "string", "description": "Optional industry id from the live filters vocabulary, e.g. label_23125000000 (258 observed 2026-10-25). Validated against the live vocabulary at run time. Unset = all industries." }, "objective": { "title": "Objective id (optional)", "type": "string", "description": "Optional campaign objective id from the live filters vocabulary (8 observed 2026-10-25). Unset = all objectives." }, "language": { "title": "Ad language id (optional)", "type": "string", "description": "Optional ad language id from the live filters vocabulary (16 observed 2026-10-25), sent upstream as ad_language. Unset = all languages." }, "exhaust": { "title": "Exhaust the filter set", "type": "boolean", "description": "Rotate all seven sort orders over this filter set (the only depth upstream serves - one page per filter set, page>=2 is a silent empty success) and dedupe by adId. Default: true when maxAds > 20, else false (the actor applies this rule when the field is omitted). Any shortfall is reported honestly in RUN_SUMMARY.depthCappedJobs." }, "maxAds": { "title": "Max ads for this job", "type": "integer", "minimum": 1, "maximum": 5000, "default": 100, "description": "Per-job cap on ad rows, clamped to 1-5000. The actor hard-caps 5,000 rows per run across all jobs. Default: 100." } } } }, "includeDetail": { "title": "Include ad detail (landing page, countries, engagement)", "type": "boolean", "description": "Enrich each ad with the detail endpoint: landing page URL, shown countries, comment/share counts, objectives, keyword list, creative pattern and synopsis. One paced GET per distinct ad (cached per run). Detail columns stay null when false or when a call does not answer - the reason is recorded in RUN_SUMMARY.detailUnavailable. Must be a real boolean; a non-boolean value aborts with an input error rather than coercing. Default: false.", "default": false }, "failSafeDeadlineMinutes": { "title": "Fail-safe deadline (minutes)", "minimum": 0, "maximum": 59, "type": "integer", "description": "Hard wall for the whole run, 0-59 minutes. On expiry running stops, rows fetched so far are kept, and RUN_SUMMARY records state=timed_out. Values above 59 are clamped (a fail-safe larger than the platform's ~60min kill is no fail-safe); 0 or negative means 'already reached' and is recorded honestly as timed_out. Default: 55.", "default": 55 } } }, "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 } } } } } } } } } }