{ "openapi": "3.0.1", "info": { "title": "TikTok Ad Library Scraper - Competitor Ads, No Login", "description": "Returns the ads advertisers run on TikTok in Europe, read from TikTok's public ad library: advertiser, ad text, video or image, first and last day shown, unique users reached, and on request payer, landing page, targeting and reach by country, age and gender. By advertiser or keyword. No login.", "version": "1.0", "x-build-id": "W7yIFC7PfxoXUaAdc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/benthepythondev~tiktok-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-benthepythondev-tiktok-ad-library-scraper", "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/benthepythondev~tiktok-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-benthepythondev-tiktok-ad-library-scraper", "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/benthepythondev~tiktok-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-benthepythondev-tiktok-ad-library-scraper", "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": { "advertisers": { "title": "Advertisers", "type": "array", "description": "Advertiser names, one search each. TikTok's own search wants a name exactly as the library writes it, so the Actor looks the name up first and reads the advertiser of that name with the most ads in your countries and dates. The run summary lists the other advertisers TikTok knows under the name.", "items": { "type": "string" } }, "keywords": { "title": "Keywords", "type": "array", "description": "Words to look for in the ad text or the advertiser's name, one search each, for example \"protein powder\". An ad must contain every word. Finds the ads of every advertiser that uses them.", "items": { "type": "string" } }, "urls": { "title": "Library links or ad ids", "type": "array", "description": "Search links copied from library.tiktok.com/ads (with the filters set there), links of single ads (…/ads/detail/?ad_id=1870698295930082) or bare ad ids. A single ad always comes with its details.", "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "Two-letter country codes: only ads shown there. Leave empty for all countries of the 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. Applies to advertisers and keywords, not to pasted links.", "items": { "type": "string" } }, "startDate": { "title": "Shown from", "type": "string", "description": "Only ads shown on or after this day (YYYY-MM-DD). Empty means 30 days before the end date, as on TikTok's own page. The library keeps ads for about a year." }, "endDate": { "title": "Shown until", "type": "string", "description": "Only ads shown on or before this day (YYYY-MM-DD). Empty means today." }, "adType": { "title": "Ad type", "enum": [ "ALL", "VIDEO", "IMAGE", "TEXT" ], "type": "string", "description": "Keep only video, image or text ads. The filter is TikTok's own.", "default": "ALL" }, "adStatus": { "title": "Ad status", "enum": [ "ALL", "ACTIVE", "INACTIVE" ], "type": "string", "description": "Active ads are the ones still running. TikTok's own page starts with active ads only, so its count is smaller than the one for all ads.", "default": "ALL" }, "minReach": { "title": "Unique users seen, at least", "enum": [ "ANY", "10K", "100K" ], "type": "string", "description": "Keep only ads that at least this many different users have seen. A cheap way to get an advertiser's important ads without the thousands of small ones.", "default": "ANY" }, "maxResults": { "title": "Maximum ads per search", "minimum": 1, "maximum": 20000, "type": "integer", "description": "Ads to save for each advertiser, keyword or search link, newest first. TikTok lists 12 ads per request.", "default": 20 }, "maxAdvertisersPerQuery": { "title": "Advertisers per name", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many advertisers to read when TikTok knows several under one name (for Nike: NIKE Retail B.V., Nike, Inc., Nike Store and more). Those with the most ads come first.", "default": 1 }, "includeDetails": { "title": "Include each ad's details", "type": "boolean", "description": "Reads every ad's own record: who paid for the ad, the advertiser's business id, country and TikTok account, landing page, button text, objective, targeting (countries, age groups, gender, interests, audience size) and unique users seen per country. Charged as a second event per ad.", "default": false }, "includeAudienceBreakdown": { "title": "Include reach by country, age and gender", "type": "boolean", "description": "With details: adds one entry per country, age group and gender with the unique users seen. Useful in JSON; in CSV and Excel an ad shown in many countries becomes hundreds of columns.", "default": false }, "onlyNewAds": { "title": "Only ads not delivered before", "type": "boolean", "description": "For scheduled runs: the first run delivers the newest ads up to the maximum, later runs with the same monitor name deliver only ads published since, so you pay only for ads that are new to you. The memory is a key-value store in your own account.", "default": false }, "monitorId": { "title": "Monitor name", "type": "string", "description": "Name of the memory used by the option above. Give each watch its own name; without a name the searches themselves are the name." } } }, "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 } } } } } } } } } }