{ "openapi": "3.0.1", "info": { "title": "TikTok Ad Library & Creative Center Scraper", "description": "Scrape TikTok ads from the public Ad Library (EEA, UK, Switzerland, Turkey) and Creative Center Top Ads: advertiser & sponsor, dates shown, reach, creatives, landing page & targeting. Filter by advertiser, region, date & audience; monitor new ads. Independent tool, not affiliated with ByteDance.", "version": "0.1", "x-build-id": "6MmWYltZJKewzXSri" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapesage~tiktok-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapesage-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/scrapesage~tiktok-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-scrapesage-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/scrapesage~tiktok-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-scrapesage-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": { "source": { "title": "Source", "enum": [ "library", "creative-center" ], "type": "string", "description": "**Ad Library** (default) = TikTok's public Commercial Content Library (library.tiktok.com): every ad shown in the EEA, the UK, Switzerland and Turkey, searchable by advertiser, region, date window, format, status and audience, with advertiser, dates shown, unique users reached and creatives. **Creative Center** = TikTok's Top Ads ranking of high-performing ads (CTR, likes, industry, objective) for many countries; anonymous visitors see a preview of each ranking (roughly 30 to a few hundred ads per country and time window).", "default": "library" }, "libraryRegions": { "title": "Ad Library regions", "type": "array", "description": "Ad Library only. Which countries' ads to search; each region is searched separately and the Max ads cap is shared fairly between them. ALL searches every library region at once.", "items": { "type": "string", "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" ], "enumTitles": [ "All regions (ALL)", "Austria (AT)", "Belgium (BE)", "Bulgaria (BG)", "Switzerland (CH)", "Cyprus (CY)", "Czech Republic (CZ)", "Germany (DE)", "Denmark (DK)", "Estonia (EE)", "Spain (ES)", "Finland (FI)", "France (FR)", "United Kingdom (GB)", "Greece (GR)", "Croatia (HR)", "Hungary (HU)", "Ireland (IE)", "Iceland (IS)", "Italy (IT)", "Liechtenstein (LI)", "Lithuania (LT)", "Luxembourg (LU)", "Latvia (LV)", "Malta (MT)", "Netherlands (NL)", "Norway (NO)", "Poland (PL)", "Portugal (PT)", "Romania (RO)", "Sweden (SE)", "Slovenia (SI)", "Slovakia (SK)", "Turkey (TR)" ] }, "default": [ "GB" ] }, "advertiserName": { "title": "Advertiser search (Ad Library)", "type": "string", "description": "Ad Library only. The library's search box, e.g. `Nike` or `L'Oreal`. With match type \"contains\" it also returns advertisers whose name merely contains the word; wrap it in double quotes (`\"NIKE Retail B.V.\"`) or set match type to \"exact\" for one advertiser only. Leave empty to browse every advertiser in the region." }, "advertiserNames": { "title": "More advertisers (Ad Library)", "type": "array", "description": "Ad Library only. Several advertisers in one run, one per line. Each advertiser is searched in each region and the Max ads cap is shared fairly between the searches.", "items": { "type": "string" } }, "advertiserMatch": { "title": "Advertiser match type (Ad Library)", "enum": [ "contains", "exact" ], "type": "string", "description": "Ad Library only. \"Contains\" is the library's normal search (broad). \"Exact\" returns only the advertiser with exactly that name, e.g. `NIKE Retail B.V.` and not resellers that mention Nike.", "default": "contains" }, "libraryStartDate": { "title": "Shown from (Ad Library)", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Ad Library only. Earliest date the ad was shown, YYYY-MM-DD. Default: 30 days before the end date." }, "libraryEndDate": { "title": "Shown until (Ad Library)", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Ad Library only. Latest date the ad was shown, YYYY-MM-DD, inclusive. Default: today." }, "librarySortBy": { "title": "Sort (Ad Library)", "enum": [ "last_shown_date,desc", "last_shown_date,asc", "create_time,desc", "create_time,asc", "impression,desc", "impression,asc", "video_views,desc", "video_views,asc", "posted_date,desc", "posted_date,asc" ], "type": "string", "description": "Ad Library only. Order of the results. In monitor mode the default changes to Created: newest first, so each check stops as soon as it reaches ads it has already seen.", "default": "last_shown_date,desc" }, "adFormat": { "title": "Ad format (Ad Library)", "enum": [ "all", "video", "image", "text" ], "type": "string", "description": "Ad Library only. Only video ads, only image ads, only text ads, or all.", "default": "all" }, "adStatus": { "title": "Ad status (Ad Library)", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Ad Library only. Only ads that are still running, only ads that have stopped, or all.", "default": "all" }, "audienceAges": { "title": "Target age (Ad Library)", "type": "array", "description": "Ad Library only. Only ads targeted at these age groups. Leave empty for every age.", "items": { "type": "string", "enum": [ "13-17", "18-24", "25-34", "35-44", "45-54", "55+" ], "enumTitles": [ "13-17", "18-24", "25-34", "35-44", "45-54", "55+" ] } }, "audienceReach": { "title": "Unique users reached (Ad Library)", "type": "array", "description": "Ad Library only. Only ads that reached this many unique users. Leave empty for any reach.", "items": { "type": "string", "enum": [ "0-10K", "10K-100K", "100K+" ], "enumTitles": [ "Under 10K (0-10K)", "10K to 100K (10K-100K)", "Over 100K (100K+)" ] } }, "audienceGender": { "title": "Target gender (Ad Library)", "enum": [ "all", "female", "male" ], "type": "string", "description": "Ad Library only. Only ads targeted at women, only at men, or all.", "default": "all" }, "includeAdDetails": { "title": "Add each ad's detail record", "type": "boolean", "description": "Ad Library: adds the advertiser's legal details (paying sponsor, business id, registry country, TikTok account and follower count), the landing-page URL and call to action when the ad has one, the campaign objective, and the targeting (age groups, genders, countries, regions and cities, reach by age and gender, audience size, interests). Creative Center: adds the landing-page URL, every country the ad runs in, comments, shares, the CTR percentile, objective weights and keywords. One extra page view per ad, billed as an ad-detail event. Off by default.", "default": false }, "maxResults": { "title": "Max ads", "minimum": 1, "type": "integer", "description": "Maximum number of ads to return across all searches (shared fairly between regions and advertisers, or between Creative Center views). If left out of an API call, 25.", "default": 25 }, "maxResultsPerQuery": { "title": "Max ads per search", "minimum": 0, "type": "integer", "description": "Optional hard cap per search (one region × advertiser in the Ad Library, one country × industry × objective view in the Creative Center). 0 = no per-search cap: Max ads is shared fairly and topped up from searches that still have ads.", "default": 0 }, "monitorMode": { "title": "Monitor mode (only new ads)", "type": "boolean", "description": "Remember the ad ids delivered on previous runs and return only ads that have not been delivered before. Ideal on a schedule to watch a competitor or a market. Nothing is billed for already-seen ads.", "default": false }, "monitorKey": { "title": "Monitor key", "type": "string", "description": "Name this monitor's memory so different saved searches track new ads separately (e.g. \"nike-uk\").", "default": "default" }, "includeVideoUrl": { "title": "Include video URLs", "type": "boolean", "description": "Include the creative's video URL(s). These are temporary TikTok links that expire after a few hours, so download promptly. The cover image and the ad's permanent library or Creative Center link are always included.", "default": true }, "includeRawData": { "title": "Include raw API record (Ad Library)", "type": "boolean", "description": "Ad Library only. Attach TikTok's raw ad record (and raw detail record when details are on) to every row as `rawItem` / `rawDetail`.", "default": false }, "countryCodes": { "title": "Countries (Creative Center)", "type": "array", "description": "Creative Center only. Country editions of the Top Ads ranking by ISO code (e.g. US, GB, DE, FR, BR, JP, SG, ID). Each country is scraped separately.", "default": [ "US" ], "items": { "type": "string" } }, "period": { "title": "Time window (Creative Center)", "enum": [ "7", "30", "180" ], "type": "string", "description": "Creative Center only. Performance window the ranking is computed over.", "default": "7" }, "orderBy": { "title": "Rank ads by (Creative Center)", "enum": [ "for_you", "ctr", "like" ], "type": "string", "description": "Creative Center only. TikTok's recommended ranking, or rank purely by click-through rate or by likes.", "default": "for_you" }, "industries": { "title": "Industries (Creative Center)", "type": "array", "description": "Creative Center only. Filter by advertiser industry, by name (e.g. \"Beauty & Personal Care\", \"Apparel & Accessories\", \"Games\", \"E-commerce\") or numeric industry id. Each industry is scraped separately; a name TikTok does not know is skipped and named in the run message.", "items": { "type": "string" } }, "objectives": { "title": "Ad objectives (Creative Center)", "type": "array", "description": "Creative Center only. Filter by campaign objective: Traffic, App Installs, Conversions, Video Views, Reach, Lead Generation, Product Sales.", "items": { "type": "string" } }, "adLanguages": { "title": "Ad languages (Creative Center)", "type": "array", "description": "Creative Center only. Filter by the language of the ad creative, by code (e.g. en, es, de, fr, pt, ja).", "items": { "type": "string" } }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy for the headless browser. Only TikTok's page and API calls use it (a few KB per search); the app's static files are fetched directly. The default (Apify datacenter proxy) works for both sources; if it cannot load TikTok's page, the run switches to residential proxy by itself.", "default": { "useApifyProxy": 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 } } } } } } } } } }