{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Scraper — TikTok Creative Center Top Ads", "description": "Scrape the TikTok Ad Library, TikTok's ads transparency archive: every ad an advertiser runs, with targeting, reach per country, landing page, payer and TikTok account. Plus TikTok Creative Center Top Ads with CTR curves. A TikTok ads scraper and ad spy for competitor ads. No login.", "version": "0.1", "x-build-id": "zEPTVc9ortCpkDRGY" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/hyperbach~tiktok-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-hyperbach-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/hyperbach~tiktok-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-hyperbach-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/hyperbach~tiktok-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-hyperbach-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": { "advertisers": { "title": "Advertisers", "type": "array", "description": "Each entry is one advertiser in TikTok's Ad Library: its name as TikTok lists it (`Samsung Electronics GmbH`), or the name with its business id (`Notion | 7377365644930662401`). A name is resolved to every business id TikTok lists under exactly that name, and each is pinned: only that advertiser's ads, not everyone who mentions it. TikTok pins by name and id together, so an id alone is not accepted — copy the pair from a row's `advertiser_name` and `advertiser_id`, or paste the library URL into Start URLs.", "items": { "type": "string", "pattern": "^(?!\\s*\\d{15,21}\\s*$)(?!\\s*https?://).*\\S.*$" }, "default": [] }, "keywords": { "title": "Keywords", "type": "array", "description": "Words searched across every advertiser's ads, as the library's search box does. Put a phrase in double quotes (`\"running shoes\"`) for the exact phrase. TikTok's total for a keyword stops at 5,000; the run walks past it by splitting the date window.", "items": { "type": "string", "pattern": "\\S" }, "default": [] }, "creators": { "title": "Creators (branded content)", "type": "array", "description": "TikTok usernames (`vikaglam`, `@vikaglam` or the profile URL): their posts in the library's \"other commercial content\" tab — branded posts with the commercial-content label. Read per country (`countries`, or all 32 when empty).", "items": { "type": "string", "pattern": "^(@?[A-Za-z0-9._]{2,24}|https?://(www\\.)?tiktok\\.com/@[A-Za-z0-9._]+.*)$" }, "default": [] }, "startUrls": { "title": "Start URLs", "type": "array", "description": "URLs copied from the browser: a library search on library.tiktok.com/ads (an advertiser or a keyword search; every filter in it is kept), a library ad (`/ads/detail/?ad_id=…`), a creator on the \"other commercial content\" tab, a Creative Center Top Ads list or ad page, or the Top Ads Spotlight page. A text file, CSV or published Google Sheet with one URL per line works too (Link remote text file).", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "adIds": { "title": "Ad ids", "type": "array", "description": "Ads to fetch again by id: library ad ids (16 digits, `1844346308991089`) or Creative Center Top Ads ids (19 digits starting with 7), or their URLs. Each comes with its full record; an id TikTok no longer has comes back as a free `not_found` row.", "items": { "type": "string", "pattern": "^(\\d{10,21}|https?://(library|ads)\\.tiktok\\.com/.+)$" }, "default": [] }, "searches": { "title": "Searches with their own filters", "type": "array", "description": "Several searches in one run, each with its own filters and cap. Each entry names one of `advertiser`, `keyword`, `url` or `creator`, plus any of `countries`, `dateRange`, `startDate`, `endDate`, `timezone`, `adStatus`, `mediaType`, `ages`, `gender`, `reach`, `sortBy`, `maxAds`. Example: `[{\"advertiser\": \"Notion | 7377365644930662401\", \"countries\": [\"GB\"]}, {\"keyword\": \"skincare\", \"dateRange\": \"last-30-days\", \"maxAds\": 200}]`.", "default": [] }, "resultType": { "title": "Result", "enum": [ "ads", "counts", "advertisers" ], "type": "string", "description": "`counts` answers \"does this advertiser run ads, and how many\" from one call per search; a search with no ads is free. `advertisers` looks names up: each business id TikTok lists for the name, whether it is an exact match, and its number of ads.", "default": "ads" }, "countries": { "title": "Countries (Ad Library)", "type": "array", "description": "Ads shown in these countries: the library covers the EU, EEA, Switzerland and the UK. Empty = all 32 in one search. Several are one search each, deduplicated (an ad shown in two is delivered once).", "items": { "type": "string", "enum": [ "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", "GB" ], "enumTitles": [ "Austria", "Belgium", "Bulgaria", "Croatia", "Cyprus", "Czechia", "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", "United Kingdom" ] }, "default": [] }, "dateRange": { "title": "Date range", "enum": [ "last-7-days", "last-30-days", "last-90-days", "last-year", "custom" ], "type": "string", "description": "When the ad was shown, as the library's own date filter, in `timezone`. `startDate` / `endDate` win over this preset when you set them.", "default": "last-year" }, "startDate": { "title": "Shown on or after", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "YYYY-MM-DD. With an end date or alone (then the 12 months before the end date). Set dates win over `dateRange`." }, "endDate": { "title": "Shown on or before", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "YYYY-MM-DD. A date after today is today." }, "timezone": { "title": "Time zone of the dates", "pattern": "^[A-Za-z_]+(/[A-Za-z0-9_+-]+)*$", "type": "string", "description": "The IANA time zone the date window is read in (`Europe/Berlin`, `America/New_York`): a day runs midnight to midnight there.", "default": "UTC" }, "adStatus": { "title": "Ad status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "The library's own status filter. The library page shows active ads by default; this Actor returns all by default.", "default": "all" }, "mediaType": { "title": "Ad type", "enum": [ "all", "video", "image" ], "type": "string", "description": "The library's ad-type filter.", "default": "all" }, "ages": { "title": "Audience age", "type": "array", "description": "Ads targeted at these age groups (the library's audience filter). Empty = any.", "items": { "type": "string", "enum": [ "13-17", "18-24", "25-34", "35-44", "45-54", "55+" ] }, "default": [] }, "gender": { "title": "Audience gender", "enum": [ "all", "female", "male" ], "type": "string", "description": "The library's audience gender filter.", "default": "all" }, "reach": { "title": "Unique users reached", "type": "array", "description": "Ads whose reach falls in these bands (the library's reach filter). Empty = any.", "items": { "type": "string", "enum": [ "0-10K", "10K-100K", "100K+" ] }, "default": [] }, "sortBy": { "title": "Sort", "enum": [ "newest", "oldest", "created_newest", "created_oldest", "impressions_high", "impressions_low" ], "type": "string", "description": "The order ads come in when a cap cuts the list. A walk that reaches the end of the list delivers every ad whatever the order.", "default": "newest" }, "includeRemovedAds": { "title": "Keep ads TikTok removed", "type": "boolean", "description": "Removed ads stay in the library with their removal reason (`is_removed`, `removal_reasons`, on the detail). Off: dropped before any detail is read, and not billed.", "default": true }, "minDaysRunning": { "title": "Min. days shown", "minimum": 0, "maximum": 3650, "type": "integer", "description": "Keep ads shown for at least this many days (first to last shown day) — the long runners. 0 = all. Filtered on the list, before any detail.", "default": 0 }, "onlyActive": { "title": "Only ads still running", "type": "boolean", "description": "Keep only the ads TikTok itself lists as active (its status filter; an ad last shown yesterday can be inactive) and not removed.", "default": false }, "topAdsCountries": { "title": "Top Ads countries", "type": "array", "description": "The Creative Center's Top Ads (TikTok's best-performing ads, worldwide) for these countries: one list per country, deduplicated. Setting one runs Top Ads; leave empty for the Ad Library only.", "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" ] }, "default": [] }, "topAdsPeriod": { "title": "Top Ads period", "enum": [ "7", "30", "180" ], "type": "string", "description": "The Top Ads period.", "default": "30" }, "topAdsSortBy": { "title": "Top Ads sort", "enum": [ "for_you", "ctr", "like", "impression", "play_2s_rate", "play_6s_rate", "cvr" ], "type": "string", "description": "TikTok's own order of the list. `for_you` changes between sessions; `ctr` is stable. `rank` on each row is the position in this order.", "default": "ctr" }, "topAdsIndustries": { "title": "Top Ads industries", "type": "array", "description": "Creative Center industries by name (`Apparel & Accessories`, `Games`) or id. The 258 names are TikTok's own.", "items": { "type": "string", "pattern": "\\S" }, "default": [] }, "topAdsObjectives": { "title": "Top Ads objectives", "type": "array", "description": "Campaign objectives to keep.", "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" ] }, "default": [] }, "topAdsLanguages": { "title": "Top Ads languages", "type": "array", "description": "Ad languages to keep.", "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" ] }, "default": [] }, "topAdsFormat": { "title": "Top Ads format", "enum": [ "all", "video", "image" ], "type": "string", "description": "TikTok's own format filter.", "default": "all" }, "topAdsLikes": { "title": "Top Ads likes tier", "enum": [ "all", "top_20", "top_40", "top_60", "top_80", "top_100" ], "type": "string", "description": "TikTok's likes tier filter.", "default": "all" }, "topAdsKeyword": { "title": "Top Ads keyword", "maxLength": 200, "type": "string", "description": "Keep Top Ads whose title or brand contains these words. TikTok answers keyword searches only to logged-in users, so the run reads the lists (with the sweep on) and matches the words itself." }, "topAdsSweep": { "title": "Go past 20 per list", "type": "boolean", "description": "Logged out, the Creative Center serves 20 ads per list. On: the run also reads the list under every sort, both directions, each objective, likes tier, format, industry and language, and deduplicates — more than 100 of TikTok's ~130 for one country and period. Each extra list is one call (about 64 per country).", "default": false }, "topAdsSpotlight": { "title": "Top Ads Spotlight", "type": "boolean", "description": "Also return the Spotlight: the ads TikTok's creative team hand-picked, with their note on why each works.", "default": false }, "topAdsDetails": { "title": "Top Ads detail", "type": "boolean", "description": "On: each Top Ad carries its landing page, countries, comments, shares, objectives and source. Off: the list fields only.", "default": true }, "topAdsMetrics": { "title": "Top Ads curves and percentiles", "type": "boolean", "description": "Each Top Ad also carries TikTok's per-second curves (CTR, conversion rate, clicks, conversions, retention) and its five percentiles. Ten calls per ad.", "default": false }, "includeDetails": { "title": "Read every library ad's detail", "type": "boolean", "description": "On: the targeting (age, gender, interests, audience size, languages, devices…), reach per country and the age × gender breakdown, the landing page with its UTMs, category, objective, CTA, payer and the advertiser's TikTok account. Off: the list fields only (dates, reach band, caption, media) — cheaper and faster.", "default": true }, "includeAdvertiserReport": { "title": "Advertiser report", "type": "boolean", "description": "One `advertiser` row per business id the run met: TikTok's own report of where its ads ran (share per country) and how many it published each month.", "default": false }, "downloadMedia": { "title": "Store the creatives", "enum": [ "none", "images", "all" ], "type": "string", "description": "TikTok's media links expire (`media_expires_at`). Store the files in the run's key-value store and get links that do not; a file an earlier run stored is linked, not fetched or billed again.", "default": "none" }, "tagAds": { "title": "Tag each ad (AI)", "type": "boolean", "description": "Typed tags from the caption and CTA: angle, CTA intent, tone, offer type, funnel stage and sentiment, each with its confidence (`analysis_*`). Same tags as our LinkedIn and Meta ads actors.", "default": false }, "analyzeAds": { "title": "Write an analysis of each ad (AI)", "type": "boolean", "description": "The hook, the offer, who it is for and the advertiser's strategy, written by a model from the ad's words.", "default": false }, "ocrImageAds": { "title": "Read the text in image ads (AI)", "type": "boolean", "description": "The words set in the artwork of image ads (`ad_ocr_text`), read by a vision model.", "default": false }, "transcribeVideos": { "title": "Transcribe video ads (AI)", "type": "boolean", "description": "What the video says (`transcript`, its language, the first 3 seconds as `hook_3s`). A silent video is not billed.", "default": false }, "openaiApiKey": { "title": "OpenAI API key (optional)", "type": "string", "description": "Your own key for `analyzeAds`, `ocrImageAds` and `transcribeVideos`, if you want the model usage on your account. Not needed: the Actor has its own." }, "summaryRows": { "title": "Summary rows", "type": "boolean", "description": "Free rows after the ads: one profile per advertiser (ads, still running, longest run, formats, domains, countries), one per landing page and one per caption hashtag.", "default": false }, "outputFormat": { "title": "Output format", "enum": [ "full", "compact" ], "type": "string", "description": "`compact` is for sheets and AI agents; billing is the same.", "default": "full" }, "maxAds": { "title": "Max ads", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Ads delivered in the whole run, exactly (0 = no limit). Never exceeded, and you are never billed for more.", "default": 0 }, "maxAdsPerSearch": { "title": "Max ads per search", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Ads per advertiser, keyword, creator, URL or Top Ads list (0 = no limit).", "default": 0 }, "onlyNewAds": { "title": "Only ads not delivered before", "type": "boolean", "description": "Monitoring: skip every ad an earlier run with the same searches delivered — not returned, not charged. An ad whose last shown day, reach band, status or likes changed comes back with `change_type: changed`.", "default": false }, "includeEndedAds": { "title": "Report ads that dropped out", "type": "boolean", "description": "Monitoring: a free `ended` row for each ad an earlier run saw that a complete walk of the same search no longer lists.", "default": false }, "stateStoreName": { "title": "Monitoring memory name", "pattern": "^[A-Za-z0-9._-]{1,100}$", "type": "string", "description": "Name of the memory `onlyNewAds` and `includeEndedAds` keep between runs. Empty = derived from the searches, so the same task always meets its own memory." }, "runTag": { "title": "Run tag", "maxLength": 200, "type": "string", "description": "Your own label, copied onto every row (`run_tag`)." }, "resumeFromRunId": { "title": "Continue an earlier run", "pattern": "^[A-Za-z0-9]{17}$", "type": "string", "description": "The id of a run of this Actor with the same input that stopped early (timeout, abort): this run continues where it stopped, without delivering or billing its ads again." } } }, "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 } } } } } } } } } }