{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Scraper - EU Ads, Targeting & Top Ads", "description": "Scrape the TikTok Ad Library (EU, EEA, UK, Switzerland, Turkey) by keyword, advertiser, country and dates: advertiser, video, first and last shown, audience, plus landing page, targeting and impressions per country. Top Ads mode adds US best performers with CTR. Error rows are free.", "version": "0.1", "x-build-id": "tC3H2R804dPTzQlHX" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapewise~tiktok-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapewise-tiktok-ads-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/scrapewise~tiktok-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-scrapewise-tiktok-ads-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/scrapewise~tiktok-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-scrapewise-tiktok-ads-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": "Source", "enum": [ "library", "topAds" ], "type": "string", "description": "Ad Library searches TikTok's public archive of ads shown in Europe and Turkey (keyword, advertiser, dates, country). Top Ads reads the Creative Center gallery of best-performing ads, including the United States, with CTR and likes.", "default": "library" }, "searchTerms": { "title": "Keywords", "type": "array", "description": "Words to search in the Ad Library, one per line, for example skincare, protein powder or vpn. TikTok matches the ad text and the advertiser name. Each keyword is searched in each country. Ad Library only.", "items": { "type": "string" } }, "advertisers": { "title": "Advertisers", "type": "array", "description": "Advertiser names, one per line, for example Nike or Temu. The Actor searches the name and keeps only ads whose advertiser name contains it (ads from other advertisers are skipped and not charged). Ad Library only.", "items": { "type": "string" } }, "country": { "title": "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": "Country where the ad was shown. The library covers the EU, the EEA, Switzerland, the UK and Turkey. Through the API you can also send a list in countries.", "default": "all" }, "lastDays": { "title": "Shown in the last N days", "minimum": 1, "maximum": 365, "type": "integer", "description": "Ads shown at any time in the last N days (UTC). Ignored when Start date is set.", "default": 30 }, "startDate": { "title": "Start date", "type": "string", "description": "Optional: ads shown on or after this date (YYYY-MM-DD). The library keeps about one year." }, "endDate": { "title": "End date", "type": "string", "description": "Optional: ads shown on or before this date (YYYY-MM-DD). Empty = today." }, "topAdsCountries": { "title": "Top Ads countries", "type": "array", "description": "Countries for Top Ads mode. Each country returns up to 20 ads per sort order, industry and objective.", "items": { "type": "string", "enum": [ "US", "GB", "CA", "AU", "DE", "FR", "IT", "ES", "NL", "SE", "RO", "TR", "BR", "MX", "AR", "CO", "JP", "KR", "ID", "MY", "PH", "SG", "TH", "VN", "PK", "SA", "AE", "ZA" ], "enumTitles": [ "United States", "United Kingdom", "Canada", "Australia", "Germany", "France", "Italy", "Spain", "Netherlands", "Sweden", "Romania", "Turkey", "Brazil", "Mexico", "Argentina", "Colombia", "Japan", "South Korea", "Indonesia", "Malaysia", "Philippines", "Singapore", "Thailand", "Vietnam", "Pakistan", "Saudi Arabia", "United Arab Emirates", "South Africa" ] }, "default": [ "US" ] }, "topAdsPeriod": { "title": "Top Ads period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Time window of the Top Ads ranking.", "default": "30" }, "topAdsSortBy": { "title": "Top Ads ranking", "type": "array", "description": "One or more rankings. TikTok serves 20 ads per ranking without login, so picking several gives more distinct ads (duplicates are removed and not charged).", "items": { "type": "string", "enum": [ "for_you", "like", "ctr", "impression", "play_2s_rate", "play_6s_rate", "cvr" ], "enumTitles": [ "For you", "Likes", "CTR", "Impressions", "2-second view rate", "6-second view rate", "Conversion rate" ] }, "default": [ "for_you" ] }, "topAdsIndustries": { "title": "Top Ads industries", "type": "array", "description": "Optional: only ads from these industries. Each industry is a separate list of up to 20 ads. Empty = all industries.", "items": { "type": "string", "enum": [ "Apparel & Accessories", "Apps", "Appliances", "Baby, Kids & Maternity", "Beauty & Personal Care", "Business Services", "E-Commerce (Non-app)", "Education", "Financial Services", "Food & Beverage", "Games", "Health", "Home Improvement", "Household Products", "Life Services", "News & Entertainment", "Pets", "Sports & Outdoor", "Tech & Electronics", "Travel", "Vehicle & Transportation" ] } }, "topAdsObjectives": { "title": "Top Ads objectives", "type": "array", "description": "Optional: only ads with these campaign objectives. Each objective is a separate list of up to 20 ads. Empty = all objectives.", "items": { "type": "string", "enum": [ "traffic", "app_installs", "conversions", "video_views", "reach", "lead_generation", "product_sales" ], "enumTitles": [ "Traffic", "App installs", "Conversions", "Video views", "Reach", "Lead generation", "Product sales" ] } }, "includeDetails": { "title": "Include ad details", "type": "boolean", "description": "On: opens each ad's detail for the landing page, call to action, objective, advertiser country and business id, TikTok account and followers, who paid for it, impressions per country and targeting (age, gender, audience size, interests). Takes about 1 to 2 seconds per ad and adds the 'Ad details' charge. Top Ads: landing page, comments, shares, countries and keywords.", "default": false }, "maxItems": { "title": "Max ads per search", "minimum": 0, "type": "integer", "description": "Upper limit of ads for each keyword or advertiser and country (Top Ads: for each country). 0 = as many as the source gives (the library stops at 5,000 per search).", "default": 50 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Apify datacenter proxy by default. If it is refused several times in a row, the Actor moves to residential proxy on its own.", "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 } } } } } } } } } }