{ "openapi": "3.0.1", "info": { "title": "TikTok DSA Ads Transparency Library Scraper", "description": "Search TikTok's EU/EEA ad transparency database by keyword, advertiser or ad ID. Get creative media, advertiser identity, impression buckets, audit status and per-region/age/gender targeting.", "version": "1.0", "x-build-id": "VN98RbYxVmnD8fOwy" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/vexaloom-labs~tiktok-dsa-ads-transparency-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-vexaloom-labs-tiktok-dsa-ads-transparency-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/vexaloom-labs~tiktok-dsa-ads-transparency-library-scraper/runs": { "post": { "operationId": "runs-sync-vexaloom-labs-tiktok-dsa-ads-transparency-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/vexaloom-labs~tiktok-dsa-ads-transparency-library-scraper/run-sync": { "post": { "operationId": "run-sync-vexaloom-labs-tiktok-dsa-ads-transparency-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": { "mode": { "title": "Data source", "enum": [ "library", "creativeCenter", "both" ], "type": "string", "description": "`library` = TikTok DSA Commercial Content Library (EU/EEA/UK/CH/TR). `creativeCenter` = global Top Ads inspiration feed. `both` = run both and label every row with `source`.", "default": "library" }, "keyword": { "title": "Keyword", "type": "string", "description": "Search ads by keyword or advertiser name. Leave empty to browse recent ads in the selected region. (mode=library)", "default": "" }, "advertiserName": { "title": "Exact advertiser name", "type": "string", "description": "Exact advertiser name as shown in the library, e.g. `NIKE Retail B.V.`. If the exact search finds nothing, the actor retries it as a keyword. (mode=library)" }, "advertiserId": { "title": "Advertiser business ID", "type": "string", "description": "Optional TikTok business ID (`adv_biz_ids`) to disambiguate an advertiser search. Use it with the exact advertiser name. (mode=library)" }, "adIds": { "title": "Ad IDs", "type": "array", "description": "Direct list of TikTok ad IDs. Skips search and opens each ad's detail page. (mode=library)", "default": [], "items": { "type": "string" } }, "startUrls": { "title": "TikTok library URLs", "type": "array", "description": "Paste TikTok library search or ad-detail URLs. Search URLs carry their own region, keyword/advertiser, dates and filters; detail URLs are read as ad IDs. (mode=library)", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "region": { "title": "Ad target country", "enum": [ "all", "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" ], "type": "string", "description": "TikTok DSA library covers EU/EEA countries plus the UK, Switzerland and Turkey. `all` searches the union (capped by TikTok), so split regions for deeper runs. (mode=library)", "default": "all" }, "startDate": { "title": "Last shown from", "type": "string", "description": "Earliest last-shown date (`YYYY-MM-DD`). Default: one year ago. (mode=library)" }, "endDate": { "title": "Last shown to", "type": "string", "description": "Latest last-shown date (`YYYY-MM-DD`). Default: today. (mode=library)" }, "sortBy": { "title": "Sort by", "enum": [ "last_shown_date,desc", "last_shown_date,asc", "create_time,desc", "create_time,asc", "impression,desc", "impression,asc" ], "type": "string", "description": "Result order. (mode=library)", "default": "last_shown_date,desc" }, "adType": { "title": "Ad type", "enum": [ "all", "video", "image", "text" ], "type": "string", "description": "Filter by creative type. (mode=library)", "default": "all" }, "adStatus": { "title": "Ad status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Active ads are still being shown; inactive ads have stopped. (mode=library)", "default": "active" }, "age": { "title": "Audience age", "type": "array", "description": "Only ads targeted at any of these age groups: `13-17`, `18-24`, `25-34`, `35-44`, `45-54`, `55+`. Leave empty for all ages. (mode=library)", "default": [], "items": { "type": "string" } }, "gender": { "title": "Audience gender", "enum": [ "all", "female", "male" ], "type": "string", "description": "Only ads targeted at this gender. (mode=library)", "default": "all" }, "uniqueReach": { "title": "Unique reach", "enum": [ "all", "under10k", "10k-100k", "over100k" ], "type": "string", "description": "Filter by TikTok's unique-users-seen band. (mode=library)", "default": "all" }, "exactPhrase": { "title": "Exact phrase", "type": "boolean", "description": "Treat the keyword as an exact phrase instead of individual words. (mode=library)", "default": false }, "includeDetails": { "title": "Fetch ad details", "type": "boolean", "description": "Open each ad's detail page for caption, CTA, landing page, advertiser identity and age/gender reach breakdown. Slower; recommended for smaller runs. (mode=library)", "default": true }, "countOnly": { "title": "Count only", "type": "boolean", "description": "Return one summary row with the number of matching ads instead of collecting ads. (mode=library)", "default": false }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum records to collect per source (1–5,000). TikTok caps a single library search at about 5,000 results.", "default": 50 }, "ccCountry": { "title": "Top Ads country", "enum": [ "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" ], "type": "string", "description": "Creative Center market. (mode=creativeCenter or both)", "default": "US" }, "ccPeriod": { "title": "Top Ads period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Performance window for Creative Center. (mode=creativeCenter or both)", "default": "30" }, "ccOrderBy": { "title": "Top Ads ranking", "enum": [ "for_you", "ctr", "like" ], "type": "string", "description": "How Creative Center ranks ads. (mode=creativeCenter or both)", "default": "for_you" }, "ccObjective": { "title": "Top Ads objective", "enum": [ "all", "1", "2", "3", "4", "5", "8", "15", "16" ], "type": "string", "description": "Campaign objective filter. (mode=creativeCenter or both)", "default": "all" }, "ccIndustry": { "title": "Top Ads industry", "enum": [ "all", "label_11105000000", "label_18110000000", "label_25300000000", "label_22000000000", "label_24118000000", "label_23113000000", "label_23124000000", "label_20112000000", "label_24112000000", "label_18101000000", "label_19105000000", "label_14105000000", "label_20104000000", "label_27104000000", "label_25302000000", "label_12104000000", "label_15101000000", "label_24113000000", "label_18107000000", "label_23130000000", "label_26000000000", "label_15000000000", "label_17106000000", "label_19100000000", "label_23102000000", "label_25303000000", "label_19102000000", "label_23127000000", "label_13111000000", "label_14101000000", "label_24100000000", "label_26107000000", "label_23128000000", "label_20109000000", "label_24103000000", "label_20101000000", "label_13110000000", "label_25308000000", "label_21999000000", "label_22109000000", "label_20999000000", "label_27101000000", "label_28101000000", "label_13108000000", "label_23107000000", "label_11999000000", "label_23133000000", "label_21104000000", "label_11107000000", "label_16102000000", "label_15106000000", "label_24119000000", "label_18100000000", "label_13101000000", "label_11110000000", "label_22112000000", "label_24117000000", "label_26100000000", "label_28000000000", "label_23112000000", "label_10000000000", "label_10100000000", "label_12101000000", "label_23100000000", "label_25304000000", "label_23132000000", "label_30000000000", "label_11109000000", "label_14100000000", "label_18000000000", "label_11104000000", "label_11106000000", "label_23122000000", "label_10104000000", "label_12109000000", "label_20108000000", "label_26113000000", "label_15107000000", "label_16105000000", "label_21102000000", "label_26109000000", "label_23125000000", "label_27000000000", "label_19101000000", "label_24110000000", "label_30102000000", "label_25311000000", "label_11100000000", "label_17103000000", "label_17105000000", "label_22101000000", "label_23117000000", "label_10101000000", "label_20100000000", "label_13114000000", "label_23000000000", "label_29999000000", "label_10105000000", "label_13100000000", "label_20000000000", "label_24102000000", "label_10106000000", "label_16100000000", "label_24101000000", "label_23103000000", "label_12106000000", "label_25310000000", "label_16000000000", "label_23126000000", "label_26101000000", "label_14999000000", "label_15105000000", "label_20102000000", "label_23110000000", "label_26102000000", "label_10999000000", "label_15100000000", "label_23116000000", "label_23118000000", "label_24109000000", "label_25313000000", "label_23123000000", "label_13999000000", "label_25312000000", "label_24116000000", "label_26104000000", "label_25305000000", "label_17000000000", "label_26105000000", "label_14106000000", "label_11101000000", "label_19000000000", "label_25999000000", "label_25306000000", "label_27103000000", "label_12108000000", "label_13113000000", "label_25000000000", "label_13117000000", "label_22107000000", "label_26114000000", "label_23101000000", "label_16999000000", "label_20106000000", "label_14104000000", "label_21100000000", "label_11112000000", "label_21103000000", "label_11102000000", "label_23114000000", "label_12107000000", "label_30101000000", "label_23134000000", "label_26106000000", "label_11111000000", "label_18106000000", "label_25309000000", "label_18111000000", "label_13104000000", "label_13109000000", "label_22106000000", "label_18112000000", "label_20107000000", "label_10103000000", "label_29101000000", "label_15102000000", "label_13102000000", "label_21105000000", "label_23131000000", "label_24114000000", "label_11000000000", "label_21101000000", "label_23108000000", "label_26108000000", "label_19104000000", "label_11108000000", "label_14102000000", "label_18104000000", "label_28100000000", "label_23115000000", "label_12103000000", "label_13116000000", "label_16104000000", "label_25301000000", "label_24108000000", "label_24120000000", "label_22111000000", "label_13103000000", "label_18108000000", "label_23105000000", "label_26103000000", "label_12999000000", "label_22113000000", "label_27999000000", "label_24999000000", "label_13112000000", "label_29102000000", "label_19106000000", "label_24104000000", "label_24107000000", "label_23104000000", "label_14107000000", "label_23119000000", "label_27102000000", "label_12102000000", "label_20103000000", "label_20111000000", "label_16101000000", "label_13000000000", "label_22102000000", "label_26111000000", "label_26999000000", "label_12000000000", "label_20110000000", "label_13107000000", "label_23109000000", "label_19103000000", "label_18102000000", "label_24106000000", "label_27100000000", "label_12105000000", "label_23111000000", "label_23106000000", "label_24000000000", "label_18103000000", "label_18109000000", "label_19999000000", "label_15104000000", "label_18999000000", "label_26112000000", "label_13105000000", "label_13115000000", "label_18105000000", "label_22105000000", "label_22108000000", "label_11103000000", "label_24115000000", "label_29103000000", "label_12100000000", "label_17999000000", "label_14000000000", "label_21000000000", "label_22999000000", "label_15999000000", "label_23129000000", "label_24111000000", "label_20105000000", "label_25307000000", "label_23999000000", "label_24105000000", "label_12110000000", "label_10102000000", "label_15103000000", "label_30100000000", "label_14103000000", "label_29000000000", "label_29100000000", "label_22110000000" ], "type": "string", "description": "Creative Center industry filter. 258 industries are available; leave `all` to sweep without an industry. (mode=creativeCenter or both)", "default": "all" }, "ccLanguage": { "title": "Top Ads language", "enum": [ "all", "en", "es", "ar", "vi", "th", "de", "id", "pt", "fr", "ms", "nl", "ja", "it", "ro", "zh-Hant", "ko" ], "type": "string", "description": "Ad language filter. (mode=creativeCenter or both)", "default": "all" }, "ccSweep": { "title": "Sweep Top Ads filters", "type": "boolean", "description": "Anonymous visitors see only 20 ads per filter combination. Sweeping periods, rankings, objectives and formats collects many more unique ads. (mode=creativeCenter or both)", "default": true }, "ccIncludeDetails": { "title": "Fetch Top Ads details", "type": "boolean", "description": "Fetch each ad's landing page, comment and share counts. (mode=creativeCenter or both)", "default": true } } }, "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 } } } } } } } } } }