{ "openapi": "3.0.1", "info": { "title": "TikTok Top Ads Scraper — Creative Center Ads & Metrics", "description": "Top-performing TikTok ads from TikTok Creative Center in 28 countries incl. Saudi Arabia and UAE: ad video, landing page, likes, comments, shares, CTR, industry and objective. New-ad alerts. EU Ad Library search experimental; blocked queries are free.", "version": "0.1", "x-build-id": "EQxlkRbMZFD3raXmT" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dottti~tiktok-ad-library/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dottti-tiktok-ad-library", "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/dottti~tiktok-ad-library/runs": { "post": { "operationId": "runs-sync-dottti-tiktok-ad-library", "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/dottti~tiktok-ad-library/run-sync": { "post": { "operationId": "run-sync-dottti-tiktok-ad-library", "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": { "sources": { "title": "Sources", "type": "array", "description": "Creative Center Top Ads works without login in 28 countries. The EU Ad Library search is experimental: TikTok often rejects automated searches, and blocked queries are never charged.", "items": { "type": "string", "enum": [ "ad_library", "creative_center" ], "enumTitles": [ "Ad Library (EU, UK, CH, TR)", "Creative Center Top Ads (28 countries)" ] }, "default": [ "creative_center" ] }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Ad Library keywords or brand names, for example nike, skincare or \"black friday\" (double quotes = exact phrase). Creative Center keyword search needs a TikTok login, so terms do not apply there.", "items": { "type": "string" } }, "advertisers": { "title": "Advertisers (Ad Library)", "type": "array", "description": "Advertiser names (Nike, Inc.) or TikTok business ids (6876449221579375362). Names are matched with the Ad Library's own advertiser suggestions; the run summary shows the match and close alternatives. Creative Center has no advertiser filter.", "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "Two-letter codes. Each term and advertiser runs once per country. Ad Library: 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, or ALL. Creative Center: AR AU BR CA CO FR DE ID IT JP MY MX NL PK PH RO SA SG ZA KR ES SE TH TR AE GB US VN. A country a source does not cover gets a free status row.", "items": { "type": "string" } }, "dateFrom": { "title": "Date from (Ad Library)", "type": "string", "description": "Optional. Ads shown on or after this date: 2026-09-01 or a relative time such as 30 days. Default: one year ago." }, "dateTo": { "title": "Date to (Ad Library)", "type": "string", "description": "Optional. Ads shown on or before this date (2026-10-27). Default: today." }, "adStatus": { "title": "Ad status (Ad Library)", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Active, inactive or all ads.", "default": "all" }, "mediaType": { "title": "Media type (Ad Library)", "enum": [ "all", "video", "image", "text" ], "type": "string", "description": "Only ads with this kind of creative.", "default": "all" }, "period": { "title": "Period (Creative Center)", "enum": [ "7", "30", "180" ], "type": "string", "description": "Top Ads time window in days: 7, 30 or 180.", "default": "30" }, "industries": { "title": "Industries (Creative Center)", "type": "array", "description": "Optional. Industry names or ids, for example Beauty & Personal Care, Financial Services, E-Commerce (Non-app), or 14000000000. Each industry runs as its own query.", "items": { "type": "string" } }, "expandIndustries": { "title": "Run every industry (Creative Center)", "type": "boolean", "description": "TikTok shows logged-out visitors 20 Top Ads per filter set. Turn this on to run all 21 main industries for each country (up to about 420 ads per country). Ignored when you list industries.", "default": false }, "objectives": { "title": "Campaign objectives (Creative Center)", "type": "array", "description": "Optional. traffic, app_install, conversion, video_view, reach, lead_generation, product_sales or app_promotion. Each objective runs as its own query.", "items": { "type": "string" } }, "adLanguage": { "title": "Ad language (Creative Center)", "type": "string", "description": "Optional. en, ar, es, fr, de, it, pt, nl, ro, vi, th, id, ms, ja, ko or zh-Hant." }, "adFormat": { "title": "Ad format (Creative Center)", "enum": [ "all", "spark", "non_spark" ], "type": "string", "description": "Spark Ads are boosted organic posts; non-Spark ads are made in Ads Manager.", "default": "all" }, "sortBy": { "title": "Sort by", "enum": [ "default", "last_shown", "newest", "reach", "ctr", "likes", "views_2s", "views_6s", "cvr" ], "type": "string", "description": "Default = last shown date in the Ad Library and \"For you\" in Creative Center. Reach works in both. CTR, likes, 2s/6s view rate and CVR are Creative Center only; newest and last shown are Ad Library only. The other source then uses its default.", "default": "default" }, "includeDetails": { "title": "Include ad details", "type": "boolean", "description": "One extra request per ad. Creative Center: landing page, comments, shares, countries, keywords. Ad Library: CTA, landing page, advertiser details and targeting by country, age and gender, when TikTok serves the detail page. Slower; no extra charge.", "default": false }, "maxAds": { "title": "Max ads per input and country", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Cap for each search term, advertiser or Top Ads query in each country. The Ad Library returns 12 ads per request, Creative Center 20.", "default": 50 }, "onlyNew": { "title": "Only new ads (alert mode)", "type": "boolean", "description": "Remembers the ads each input returned before and delivers only ads not seen yet. Schedule the actor to get new-ad alerts. The first run delivers everything and saves the baseline. You pay only for new ads.", "default": false }, "stateName": { "title": "Alert state name", "type": "string", "description": "Name of the saved state for Only new ads. Use a different name for each watchlist or schedule.", "default": "default" }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Leave empty for the automatic ladder: no proxy first, then Apify datacenter, then residential only if TikTok refuses. Set a proxy here to force it." }, "autoProxyFallback": { "title": "Automatic proxy fallback", "type": "boolean", "description": "Move to a proxy when TikTok refuses direct requests.", "default": true }, "allowResidentialFallback": { "title": "Allow residential proxy as last step", "type": "boolean", "description": "Residential proxy uses more platform credit (included in the price). Turn off to stop at datacenter.", "default": true }, "maxRetries": { "title": "Max retries per request", "minimum": 1, "maximum": 8, "type": "integer", "description": "Retries per request, each on a fresh session, when TikTok answers with an error or drops the connection.", "default": 4 } } }, "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 } } } } } } } } } }