{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Scraper - Ad Library by Keyword and Country", "description": "Scrape TikTok ads from TikTok's public ad library by keyword, advertiser, country or date. Each ad has the advertiser, caption, first and last shown dates, countries, a reach band, video, thumbnail, call to action and landing page. EEA and UK ads only, no US. $0.45 per 1,000 ads.", "version": "0.1", "x-build-id": "QsWaf4gpgFcKpakXm" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dami_studio~tiktok-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dami_studio-tiktok-ads-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/dami_studio~tiktok-ads-scraper/runs": { "post": { "operationId": "runs-sync-dami_studio-tiktok-ads-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/dami_studio~tiktok-ads-scraper/run-sync": { "post": { "operationId": "run-sync-dami_studio-tiktok-ads-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": { "searchTerms": { "title": "Search terms", "minItems": 0, "maxItems": 20, "type": "array", "description": "Keywords to search for. Matches both advertiser names and ad captions, so \"running shoes\" returns ads whose copy mentions running shoes. Up to 20 per run; the row budget is shared evenly between them.", "items": { "type": "string" } }, "advertiserNames": { "title": "Advertiser names", "minItems": 0, "maxItems": 20, "type": "array", "description": "Registered advertiser names, for example \"NIKE Retail B.V.\". Each is resolved against the library's own advertiser register first, then that advertiser's ads are pulled. Typing a brand word like \"Nike\" picks up registered entities whose name starts with it.", "items": { "type": "string" } }, "adLibraryUrls": { "title": "Ad Library URLs", "minItems": 0, "maxItems": 20, "type": "array", "description": "Paste addresses straight from library.tiktok.com/ads. The country, date range, advertiser, sort order and format filters already in the URL are read back out and used as they are.", "items": { "type": "string" } }, "countries": { "title": "Ad target countries", "minItems": 0, "maxItems": 32, "type": "array", "description": "Two-letter codes for the countries an ad was shown in, or \"all\". Only these exist in this 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. Leave empty to search all of them. On its own, with no search terms, it means the ads running in these countries.", "items": { "type": "string" } }, "dateFrom": { "title": "Shown from", "type": "string", "description": "The start of the window an ad must have run in, as YYYY-MM-DD. Defaults to 30 days ago. The library holds nothing before 2022-10-01 and an earlier date is moved forward to it." }, "dateTo": { "title": "Shown until", "type": "string", "description": "The end of the window, as YYYY-MM-DD. Defaults to today." }, "maxItems": { "title": "Maximum rows", "minimum": 1, "maximum": 20000, "type": "integer", "description": "Total number of ads to return across every search term, advertiser and URL. The budget is shared evenly between them. Keep it low while you are testing - you pay per row." }, "includeAdDetails": { "title": "Include the per-ad transparency record", "type": "boolean", "description": "On by default. This is the only source of the landing page URL, the call to action, the campaign objective, the advertiser's registry country, the full list of targeted countries, the audience size and the per-country impression bands. Turn it off for a faster, lighter run with those fields left null." }, "adFormat": { "title": "Creative format", "enum": [ "all", "video", "image", "text" ], "type": "string", "description": "Return every format, or only video, image or text ads." }, "adStatus": { "title": "Ad status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Return every ad, only ads still running, or only ads that have stopped." }, "sortBy": { "title": "Order", "enum": [ "create_time,desc", "create_time,asc", "last_shown_date,desc", "last_shown_date,asc", "impression,desc", "impression,asc" ], "type": "string", "description": "How the library should order the results before they are paged. Published-date descending is the default because it is the ordering the library itself repeats and skips least." }, "proxyUrls": { "title": "Your own proxy servers (optional)", "minItems": 0, "maxItems": 50, "type": "array", "description": "Leave this empty for a normal run. Fill it in only if you want the traffic to leave through proxy servers you already pay for, one URL per line, in the form http://user:pass@host:port.", "items": { "type": "string" } }, "sessionCookies": { "title": "Account cookies (not needed)", "minItems": 0, "maxItems": 10, "type": "array", "description": "Optional: your own session, used only for your run. You are responsible for using it within the site's terms. Runs work without it." } } }, "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 } } } } } } } } } }