{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Scraper - Ad Library at $0.45/1K", "description": "Reads TikTok's public Commercial Content Library by keyword, advertiser, country and date. One row per ad: advertiser, caption, first and last shown dates, countries targeted, unique-users band, video, thumbnail, CTA and landing URL. EEA and UK only - no US edition.", "version": "0.1", "x-build-id": "d6sdxR2NtvLlwxwem" }, "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 every ad 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 complete ad set is pulled. Typing a brand word like \"Nike\" picks up every registered entity 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 \"every ad 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. By default the run rotates a large pool of addresses that cost you nothing per gigabyte. Fill it in only if you specifically want the traffic to leave through proxy servers you already pay for, in the form http://user:pass@host:port.", "items": { "type": "string" } }, "sessionCookies": { "title": "Your own account cookies (optional)", "minItems": 0, "maxItems": 10, "type": "array", "description": "Optional, and almost never needed. The Commercial Content Library is a public transparency archive and this Actor reads it without any account. Supply your own TikTok account cookie only as a safety net for the day the library stops serving anonymous callers. In Chrome: F12 -> Application -> Cookies -> tiktok.com, and copy the value of sessionid. Anyone with this value can act as your account, so treat it like a password.", "items": { "type": "string" } } } }, "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 } } } } } } } } } }