{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Scraper - Ad Library & Creative Center Ads", "description": "Scrape TikTok ads from the TikTok Ad Library and Creative Center: advertiser, ad text, video, dates, unique users seen, targeting, reach by country, age and gender, landing URL, CTR, likes. Search by keyword, advertiser or country, monitor new ads. From $0.99 per 1,000 ads. No login.", "version": "0.1", "x-build-id": "nIAkMu0Bj5mDP3kyZ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/topapi~tiktok-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-topapi-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/topapi~tiktok-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-topapi-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/topapi~tiktok-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-topapi-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": { "sources": { "title": "Ad sources", "uniqueItems": true, "type": "array", "description": "Which TikTok ad sources to read. Ad Library = ads shown in the EU, EEA, UK, Switzerland and Turkey, with reach and targeting; Creative Center = global top ads with CTR and likes.", "items": { "type": "string", "enum": [ "library", "creative_center", "spotlight", "other_commercial_content" ], "enumTitles": [ "Ad Library (EU, EEA, UK, CH and TR ads)", "Creative Center Top Ads", "Top Ads Spotlight (case studies)", "Other commercial content (creator partnerships)" ] }, "default": [ "library" ] }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Keywords, e.g. \"running shoes\", \"nike\". Quote a term for an exact phrase. Other commercial content: creator usernames. Creative Center: matched on the ad caption.", "items": { "type": "string" } }, "advertiserNames": { "title": "Advertiser names", "type": "array", "description": "Advertisers as the Ad Library names them, e.g. \"Nike\", \"Zalando\". Looked up in TikTok's own advertiser search box. Pin any entity with \"Name|advertiser id\".", "items": { "type": "string" } }, "advertiserMatch": { "title": "Advertiser match", "enum": [ "contains", "exact" ], "type": "string", "description": "Default: every advertiser whose name starts with the term as a whole word, e.g. Nike Store, Nike, Inc. for \"nike\" (not NIKELAB LTD or handles like nike_shop).", "default": "contains" }, "adIds": { "title": "Ad ids", "type": "array", "description": "Ad Library ad ids (e.g. 1876662213746929) or Creative Center top ad ids (e.g. 7686346996722745360). Each id returns that ad.", "items": { "type": "string" } }, "startUrls": { "title": "TikTok URLs", "type": "array", "description": "Ad Library search or ad URLs (library.tiktok.com/ads?...), other commercial content URLs, Creative Center top ad or Top Ads URLs.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "countries": { "title": "Ad Library countries", "uniqueItems": true, "type": "array", "description": "Countries where the ads were shown (Ad Library; also other commercial content, except Switzerland and the UK). All = every country the library covers.", "items": { "type": "string", "enum": [ "all", "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IS", "IE", "IT", "LV", "LI", "LT", "LU", "MT", "NL", "NO", "PL", "PT", "RO", "SK", "SI", "ES", "SE", "CH", "TR", "GB" ], "enumTitles": [ "All countries", "Austria", "Belgium", "Bulgaria", "Croatia", "Cyprus", "Czech Republic", "Denmark", "Estonia", "Finland", "France", "Germany", "Greece", "Hungary", "Iceland", "Ireland", "Italy", "Latvia", "Liechtenstein", "Lithuania", "Luxembourg", "Malta", "Netherlands", "Norway", "Poland", "Portugal", "Romania", "Slovakia", "Slovenia", "Spain", "Sweden", "Switzerland", "Turkey", "United Kingdom" ] }, "default": [ "all" ] }, "dateFrom": { "title": "Shown from", "type": "string", "description": "Ads last shown on or after this date (YYYY-MM-DD or relative, e.g. 12 months). Empty = since October 2022, the library's start." }, "dateTo": { "title": "Shown until", "type": "string", "description": "Ads last shown on or before this date. Empty = today." }, "timezone": { "title": "Timezone", "type": "string", "description": "IANA timezone for the dates above, e.g. Europe/Paris. Default UTC.", "default": "UTC" }, "sortBy": { "title": "Sort ads by", "enum": [ "last_shown_date,desc", "last_shown_date,asc", "create_time,desc", "create_time,asc", "impression,desc", "impression,asc" ], "type": "string", "description": "Order of Ad Library results. Advertiser searches follow it; keyword searches are read one week at a time, newest week first, in TikTok's order within each week.", "default": "last_shown_date,desc" }, "adType": { "title": "Ad format", "enum": [ "all", "video", "image", "text" ], "type": "string", "description": "Ad Library format filter.", "default": "all" }, "adStatus": { "title": "Ad status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Active = still being shown.", "default": "all" }, "ages": { "title": "Target ages", "uniqueItems": true, "type": "array", "description": "Ads targeted at these age groups.", "items": { "type": "string", "enum": [ "all", "13-17", "18-24", "25-34", "35-44", "45-54", "55+" ], "enumTitles": [ "All ages", "13-17", "18-24", "25-34", "35-44", "45-54", "55+" ] }, "default": [ "all" ] }, "adReach": { "title": "Unique users seen", "uniqueItems": true, "type": "array", "description": "Ad Library reach buckets.", "items": { "type": "string", "enum": [ "all", "0-10K", "10K-100K", "100K+" ], "enumTitles": [ "Any reach", "Under 10K", "10K to 100K", "Over 100K" ] }, "default": [ "all" ] }, "gender": { "title": "Target gender", "enum": [ "ALL", "FEMALE", "MALE" ], "type": "string", "description": "Ads targeted at this gender.", "default": "ALL" }, "occSortBy": { "title": "Other commercial content order", "enum": [ "posted_date,desc", "posted_date,asc", "video_views,desc", "video_views,asc" ], "type": "string", "description": "Order of creators' commercial posts.", "default": "posted_date,desc" }, "ccCountries": { "title": "Creative Center countries", "uniqueItems": true, "type": "array", "description": "Top ads shown in these countries. Empty = all regions.", "items": { "type": "string", "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" ], "enumTitles": [ "Argentina", "Australia", "Brazil", "Canada", "Colombia", "France", "Germany", "Indonesia", "Italy", "Japan", "Malaysia", "Mexico", "Netherlands", "Pakistan", "Philippines", "Romania", "Saudi Arabia", "Singapore", "South Africa", "South Korea", "Spain", "Sweden", "Thailand", "Turkey", "United Arab Emirates", "United Kingdom", "United States", "Vietnam" ] } }, "ccPeriod": { "title": "Period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Top ads of the last 7, 30 or 180 days.", "default": "30" }, "ccIndustries": { "title": "Industries", "uniqueItems": true, "type": "array", "description": "Creative Center industries. Empty = all.", "items": { "type": "string", "enum": [ "22000000000", "16000000000", "20000000000", "12000000000", "14000000000", "24000000000", "30000000000", "10000000000", "13000000000", "27000000000", "25000000000", "29000000000", "21000000000", "18000000000", "26000000000", "23000000000", "19000000000", "28000000000", "15000000000", "17000000000", "11000000000" ], "enumTitles": [ "Apparel & Accessories", "Appliances", "Apps", "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" ] } }, "ccObjectives": { "title": "Campaign objectives", "uniqueItems": true, "type": "array", "description": "Empty = all objectives.", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "8", "15" ], "enumTitles": [ "Traffic", "App installs", "Conversions", "Video views", "Reach", "Lead generation", "Product sales" ] } }, "ccAdLanguages": { "title": "Ad languages", "uniqueItems": true, "type": "array", "description": "Language of the ad. Empty = all.", "items": { "type": "string", "enum": [ "en", "es", "ar", "vi", "th", "de", "id", "pt", "fr", "ms", "nl", "ja", "it", "ro", "zh-Hant", "ko" ], "enumTitles": [ "English", "Spanish", "Arabic", "Vietnamese", "Thai", "German", "Indonesian", "Portuguese", "French", "Malay", "Dutch", "Japanese", "Italian", "Romanian", "Chinese (Traditional)", "Korean" ] } }, "ccAdFormat": { "title": "Spark Ads", "enum": [ "all", "spark", "non_spark" ], "type": "string", "description": "Spark Ads boost an organic TikTok post; non-Spark Ads are regular in-feed ads.", "default": "all" }, "ccLikes": { "title": "Likes tier", "uniqueItems": true, "type": "array", "description": "Creative Center likes percentile. Empty = all.", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5" ], "enumTitles": [ "Top 1-20%", "Top 21-40%", "Top 41-60%", "Top 61-80%", "Top 81-100%" ] } }, "ccSortBy": { "title": "Sort top ads by", "enum": [ "for_you", "impression", "ctr", "play_2s_rate", "play_6s_rate", "cvr", "like" ], "type": "string", "description": "TikTok serves 20 top ads per filter set; for more, the actor also reads the other sorts, countries and industries.", "default": "for_you" }, "excludeKeywords": { "title": "Exclude keywords", "type": "array", "description": "Drop ads whose title, advertiser, brand or creator contains any of these words, e.g. \"giveaway\".", "items": { "type": "string" } }, "minLikes": { "title": "Minimum likes", "minimum": 0, "maximum": 100000000, "type": "integer", "description": "Creative Center and Spotlight: keep top ads with at least this many likes. 0 = off." }, "includeRemovedAds": { "title": "Include removed ads", "type": "boolean", "description": "Ad Library ads TikTok removed show no advertiser or creative. Off = skip them (not delivered, not charged).", "default": false }, "includeDetails": { "title": "Ad Library details", "type": "boolean", "description": "Adds targeting, unique users seen by country x age x gender, landing URL, CTA, objective, payer and the advertiser's TikTok account. Add-on ad-details.", "default": false }, "maxDetails": { "title": "Max ads with details", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Ad Library details on at most this many ads, from searches, ad ids and ad URLs alike; the rest come without them (no ad-details charge). 0 = no limit. Top ad details are not counted." }, "includeTopAdDetails": { "title": "Top ad details", "type": "boolean", "description": "Creative Center: landing page, objectives, voice-over, comments, shares, countries, TikTok's creative summary. Add-on top-ad-details.", "default": false }, "keyframeMetrics": { "title": "Keyframe metrics", "uniqueItems": true, "type": "array", "description": "Creative Center second-by-second curves with highlight seconds. Included free.", "items": { "type": "string", "enum": [ "retain_ctr", "retain_cvr", "click_cnt", "convert_cnt", "play_retain_cnt" ], "enumTitles": [ "CTR by second", "CVR by second", "Clicks by second", "Conversions by second", "Retention by second" ] } }, "monitorMode": { "title": "Only new ads", "type": "boolean", "description": "Return only ads not delivered by earlier runs with the same monitor store. Pairs with a daily schedule.", "default": false }, "monitorStoreName": { "title": "Monitor store name", "type": "string", "description": "Named key-value store that remembers delivered ads. One name per watch list. Default tiktok-ads-library-monitor." }, "monitorChanges": { "title": "Also return changed ads", "type": "boolean", "description": "Monitor mode: re-deliver known Ad Library ads whose last shown date or reach changed (charged again).", "default": false }, "maxResults": { "title": "Max ads", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Total ads per run. 0 = no limit. TikTok shows 5,000 as the total of any keyword search; the actor reads past it, one week at a time.", "default": 100 }, "maxResultsPerSearch": { "title": "Max ads per search", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Cap per search term, advertiser, URL or source. 0 = no per-search cap." }, "compact": { "title": "Compact output", "type": "boolean", "description": "Core fields only, sized for AI agents and MCP. An add-on you turn on keeps all its fields and detailsFetched, so no charged field is dropped; keyframes are kept too.", "default": false }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Optional. By default the actor connects directly and switches to Apify's datacenter, then residential proxy by itself if TikTok refuses." }, "maxConcurrency": { "title": "Parallel sessions", "minimum": 1, "maximum": 10, "type": "integer", "description": "TikTok sessions used in parallel (detail pages). 4 is a safe default.", "default": 4 } } }, "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 } } } } } } } } } }