{
"openapi": "3.0.1",
"info": {
"title": "TikTok Ads Library Scraper — Ads, Targeting & Hashtag Trends",
"description": "TikTok ads scraper: pull Creative Center Top Ads and the EU Ad Library in one actor. Export CTR, likes, comments, shares, cost score, campaign objective, industry, landing page and MP4 video URLs in five resolutions. Optional per-ad audience targeting and reach.",
"version": "0.0",
"x-build-id": "hIpM7bmNOzlFyiJH8"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/memo23~tiktok-ads-scraper-cheerio/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-memo23-tiktok-ads-scraper-cheerio",
"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/memo23~tiktok-ads-scraper-cheerio/runs": {
"post": {
"operationId": "runs-sync-memo23-tiktok-ads-scraper-cheerio",
"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/memo23~tiktok-ads-scraper-cheerio/run-sync": {
"post": {
"operationId": "run-sync-memo23-tiktok-ads-scraper-cheerio",
"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": "Mode",
"enum": [
"trends",
"topAds",
"adLibrary"
],
"type": "string",
"description": "Trends = popular hashtags from the TikTok Creative Center (rank, post counts, weekly trend).
Top Ads = the best-performing ad creatives from the Creative Center, ranked by CTR / likes / cost, with video URLs, landing page, objective and engagement.
Ad Library = individual ad creatives from library.tiktok.com (advertiser, video, targeting by age/gender/region, etc.).",
"default": "trends"
},
"country": {
"title": "Country / region",
"enum": [
"",
"AR",
"AU",
"AT",
"BH",
"BD",
"BY",
"BE",
"BR",
"BG",
"KH",
"CA",
"CL",
"CO",
"HR",
"CZ",
"DK",
"EG",
"EE",
"FI",
"FR",
"DE",
"GR",
"HU",
"IS",
"ID",
"IQ",
"IE",
"IL",
"IT",
"JP",
"JO",
"KZ",
"KW",
"LV",
"LB",
"LT",
"LU",
"MO",
"MY",
"MX",
"MA",
"MM",
"NL",
"NZ",
"NG",
"NO",
"OM",
"PK",
"PE",
"PH",
"PL",
"PT",
"QA",
"RO",
"SA",
"SG",
"SK",
"ZA",
"KR",
"ES",
"SE",
"CH",
"TW",
"TH",
"TR",
"UA",
"AE",
"GB",
"US",
"UZ",
"VN"
],
"type": "string",
"description": "Two-letter country code. Empty string means all regions (Ad Library mode) or unset (Trends mode).
Ad Library mode is only available in EU/EEA + UK + TR (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). Other values silently fall back to all.",
"default": "US"
},
"days": {
"title": "Time window",
"enum": [
"7",
"30",
"120"
],
"type": "string",
"description": "Look-back period for trending hashtags.",
"default": "7"
},
"isNewToTop100": {
"title": "Only newcomers in the Top 100",
"type": "boolean",
"description": "If checked, only return hashtags that newly entered the Top 100 in the chosen window.",
"default": false
},
"startUrl": {
"title": "Library URL (optional shortcut)",
"type": "string",
"description": "Paste a URL from library.tiktok.com/ads or library.tiktok.com/other-commercial-content (with your filters applied). The actor extracts region, search_terms, adv_name, sort_type, start_time, end_time, strips pagination params, and auto-detects the mode (ad library vs commercial content). Leave empty to use the discrete filter fields below."
},
"sourceType": {
"title": "Library section",
"enum": [
"ad_library",
"other_commercial_content"
],
"type": "string",
"description": "Which library surface to scrape when no URL is supplied. Ad Library = paid TikTok ads with advertiser transparency data. Other Commercial Content = branded creator posts (disclosed brand partnerships).",
"default": "ad_library"
},
"searchQuery": {
"title": "Search query",
"type": "string",
"description": "Keyword or advertiser name to search. Wrap it in quotes, like \"black friday\", to match that exact phrase (Ad Library). In Other Commercial Content mode, this searches the creator username."
},
"advertiserName": {
"title": "Advertiser name (Ad Library only)",
"type": "string",
"description": "Optional filter by registered advertiser name. Ignored in Other Commercial Content mode."
},
"startDate": {
"title": "Start date",
"type": "string",
"description": "Earliest last-shown / posted date to include (YYYY-MM-DD). Defaults to 30 days ago. TikTok's Ad Library begins on 2022-10-01, so an earlier date searches from there."
},
"endDate": {
"title": "End date",
"type": "string",
"description": "Latest last-shown / posted date to include (YYYY-MM-DD). Defaults to today."
},
"sortBy": {
"title": "Sort by",
"enum": [
"last_shown_date,desc",
"last_shown_date,asc",
"first_shown_date,desc",
"first_shown_date,asc",
"reach_high",
"reach_low",
"views_high",
"views_low"
],
"type": "string",
"description": "Sort order for results. Reach / views options rank by TikTok's impression sort (Ad Library) or video-views sort (Other Commercial Content) — largest to smallest (high) or smallest to largest (low).",
"default": "last_shown_date,desc"
},
"adStatus": {
"title": "Ad status (Ad Library only)",
"enum": [
"all",
"active",
"inactive"
],
"type": "string",
"description": "Ads still running, ads that have stopped, or both. TikTok's own site shows active ads by default; this actor returns both unless you pick one.",
"default": "all"
},
"adType": {
"title": "Ad format (Ad Library only)",
"enum": [
"all",
"video",
"image",
"text"
],
"type": "string",
"description": "Only ads in this format.",
"default": "all"
},
"targetAges": {
"title": "Targeted age groups (Ad Library only)",
"type": "array",
"description": "Only ads targeted at one or more of 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+"
]
},
"default": []
},
"targetGender": {
"title": "Targeted gender (Ad Library only)",
"enum": [
"all",
"female",
"male"
],
"type": "string",
"description": "Only ads targeted at this gender alone. Ads shown to everyone are left out when you pick one.",
"default": "all"
},
"uniqueReach": {
"title": "Unique reach (Ad Library only)",
"type": "array",
"description": "Only ads seen by this many unique users. Pick one or more ranges; leave empty for any reach.",
"items": {
"type": "string",
"enum": [
"under_10k",
"10k_100k",
"over_100k"
],
"enumTitles": [
"Under 10K",
"10K – 100K",
"Over 100K"
]
},
"default": []
},
"period": {
"title": "Ranking window (days)",
"enum": [
"7",
"30",
"180"
],
"type": "string",
"description": "Lookback window for the top-ads ranking: last 7, 30, or 180 days.",
"default": "30"
},
"orderBy": {
"title": "Rank ads by",
"type": "string",
"description": "How the top ads are ranked.",
"default": "for_you"
},
"industry": {
"title": "Industry (Top Ads)",
"enum": [
"all",
"22000000000",
"16000000000",
"20000000000",
"12000000000",
"14000000000",
"24000000000",
"30000000000",
"10000000000",
"13000000000",
"27000000000",
"25000000000",
"29000000000",
"21000000000",
"18000000000",
"26000000000",
"23000000000",
"19000000000",
"28000000000",
"15000000000",
"17000000000",
"11000000000"
],
"type": "string",
"description": "Top Ads only. Show the ranking for one top-level industry. All (the default) applies no industry filter. To pick a sub-category, use the field below, which overrides this one when set.",
"default": "all"
},
"industryId": {
"title": "Industry incl. sub-categories (Top Ads)",
"enum": [
"",
"22000000000",
"22102000000",
"22101000000",
"22107000000",
"22108000000",
"22109000000",
"22106000000",
"22999000000",
"22114000000",
"22112000000",
"22105000000",
"22113000000",
"22110000000",
"22111000000",
"16000000000",
"16105000000",
"16104000000",
"16101000000",
"16102000000",
"16999000000",
"16100000000",
"20000000000",
"20101000000",
"20110000000",
"20104000000",
"20106000000",
"20109000000",
"20107000000",
"20102000000",
"20105000000",
"20999000000",
"20111000000",
"20103000000",
"20100000000",
"20108000000",
"20112000000",
"12000000000",
"12104000000",
"12108000000",
"12100000000",
"12102000000",
"12110000000",
"12105000000",
"12107000000",
"12109000000",
"12103000000",
"12999000000",
"12101000000",
"12106000000",
"14000000000",
"14105000000",
"14104000000",
"14107000000",
"14106000000",
"14101000000",
"14100000000",
"14999000000",
"14103000000",
"14102000000",
"24000000000",
"24108000000",
"24118000000",
"24105000000",
"24103000000",
"24104000000",
"24109000000",
"24114000000",
"24107000000",
"24116000000",
"24120000000",
"24119000000",
"24117000000",
"24111000000",
"24106000000",
"24112000000",
"24101000000",
"24999000000",
"24113000000",
"24100000000",
"24102000000",
"24110000000",
"24115000000",
"30000000000",
"30100000000",
"30102000000",
"30101000000",
"10000000000",
"10100000000",
"10102000000",
"10105000000",
"10106000000",
"10999000000",
"10103000000",
"10101000000",
"10104000000",
"13000000000",
"13100000000",
"13108000000",
"13117000000",
"13115000000",
"13116000000",
"13112000000",
"13107000000",
"13104000000",
"13102000000",
"13110000000",
"13111000000",
"13109000000",
"13999000000",
"13105000000",
"13113000000",
"13101000000",
"13114000000",
"13103000000",
"27000000000",
"27103000000",
"27104000000",
"27100000000",
"27101000000",
"27102000000",
"27999000000",
"25000000000",
"25212000000",
"25301000000",
"25202000000",
"25217100000",
"25216100000",
"25216101000",
"25302000000",
"25216102000",
"25100000000",
"25201000000",
"25300000000",
"25211000000",
"25203000000",
"25210000000",
"25313000000",
"25204000000",
"25216103000",
"25217101000",
"25303000000",
"25999000000",
"25216999000",
"25205000000",
"25311000000",
"25206000000",
"25304000000",
"25306000000",
"25208000000",
"25213000000",
"25305000000",
"25214000000",
"25215000000",
"25307000000",
"25207000000",
"25217102000",
"25308000000",
"25209000000",
"25309000000",
"25218000000",
"25310000000",
"25312000000",
"25200000000",
"29000000000",
"29102000000",
"29101000000",
"29100000000",
"29103000000",
"29999000000",
"21000000000",
"21102000000",
"21101000000",
"21103000000",
"21104000000",
"21100000000",
"21999000000",
"21105000000",
"18000000000",
"18106000000",
"18110000000",
"18104000000",
"18101000000",
"18102000000",
"18105000000",
"18108000000",
"18109000000",
"18999000000",
"18112000000",
"18100000000",
"18113000000",
"18103000000",
"18107000000",
"18111000000",
"26000000000",
"26114000000",
"26112000000",
"26102000000",
"26115000000",
"26113000000",
"26108000000",
"26104000000",
"26105000000",
"26111000000",
"26999000000",
"26101000000",
"26106000000",
"26107000000",
"26109000000",
"26103000000",
"26100000000",
"23000000000",
"23113000000",
"23114000000",
"23122000000",
"23102000000",
"23126000000",
"23108000000",
"23105000000",
"23111000000",
"23116000000",
"23104000000",
"23128000000",
"23107000000",
"23119000000",
"23124000000",
"23125000000",
"23127000000",
"23115000000",
"23106000000",
"23109000000",
"23110000000",
"23100000000",
"23999000000",
"23129000000",
"23101000000",
"23118000000",
"23130000000",
"23131000000",
"23103000000",
"23134000000",
"23123000000",
"23132000000",
"23112000000",
"23117000000",
"23133000000",
"19000000000",
"19999000000",
"19103000000",
"19101000000",
"19102000000",
"19105000000",
"19106000000",
"19104000000",
"19100000000",
"28000000000",
"28100000000",
"28101000000",
"15000000000",
"15105000000",
"15102000000",
"15103000000",
"15101000000",
"15104000000",
"15108000000",
"15100000000",
"15106000000",
"15107000000",
"15999000000",
"17000000000",
"17103000000",
"17999000000",
"17105000000",
"17106000000",
"11000000000",
"11111000000",
"11110000000",
"11101000000",
"11103000000",
"11102000000",
"11100000000",
"11107000000",
"11112000000",
"11104000000",
"11108000000",
"11106000000",
"11999000000",
"11105000000",
"11109000000"
],
"type": "string",
"description": "Full Creative Center industry taxonomy: 21 top-level industries and their sub-categories (e.g. Beauty & Personal Care > Skincare). TikTok filters by top-level industry only, so a sub-category is filtered by the actor inside its parent industry's board of about 20 ads and can return few ads or none. When set, this overrides the top-level Industry filter above for Top Ads mode. Leave unset to use the Industry filter.",
"default": ""
},
"objective": {
"title": "Campaign objective (optional)",
"type": "string",
"description": "Filter ads by their campaign objective. Leave empty for all.",
"default": ""
},
"adLanguage": {
"title": "Ad language (optional)",
"type": "string",
"description": "Two-letter language code to filter creatives by language (e.g. en, es, de). Leave empty for all.",
"default": ""
},
"adFormat": {
"title": "Ad format",
"enum": [
"",
"spark_ads",
"non_spark_ads"
],
"type": "string",
"description": "Restrict to Spark Ads (ads promoted from an existing organic TikTok post) or Non-Spark Ads (standalone ad creatives). Leave empty for all.",
"default": ""
},
"keyword": {
"title": "Keyword filter (Top Ads)",
"type": "string",
"description": "Top Ads only. Keeps just the ads whose title or brand name contains this text. Applied by the actor to the ranking TikTok returns, since TikTok's Top Ads board has no keyword search. Example: nike. Leave empty for no filter.",
"default": ""
},
"minLikes": {
"title": "Minimum likes (Top Ads)",
"minimum": 0,
"type": "integer",
"description": "Top Ads only. Keeps just the ads with at least this many likes. Applied by the actor to the ranking TikTok returns (TikTok offers no likes filter). Example: 1000. Leave empty for no filter."
},
"extractDetails": {
"title": "Fetch full ad details",
"type": "boolean",
"description": "Top Ads: adds each ad's full details (target country list, landing page, comments/shares, keyword list, objectives). Off = faster/cheaper, list-level fields only (CTR, cost, likes, video).
Ad Library: no effect. For audience targeting and per-country reach on Ad Library rows, turn on Ad Library: fetch per-ad audience targeting.",
"default": true
},
"extractTargeting": {
"title": "Ad Library: fetch per-ad audience targeting (billed extra)",
"type": "boolean",
"description": "Ad Library only. Adds each ad's audience targeting and reach: the countries it ran in, age groups, genders, per-country impression buckets, the full country x age x gender breakdown, plus advertising objective, the advertiser's business ID, registry location and who paid for the ad. Each ad takes about 2-3 seconds more, so runs are noticeably slower, and it is billed at $0.0015 per ad on top of the result price. You are only charged for ads whose targeting is actually retrieved. Leave off for a fast, cheap listing-only run.",
"default": false
},
"resultsLimit": {
"title": "Max results",
"minimum": 1,
"maximum": 1000000,
"type": "integer",
"description": "Hard cap on the number of records pushed to the dataset. Applies to every mode — Trends stops after this many hashtags, Top Ads / Ad Library after this many ads.",
"default": 100
},
"maxConcurrency": {
"title": "Max concurrency",
"type": "integer",
"description": "Maximum number of parallel requests.",
"default": 10
},
"minConcurrency": {
"title": "Min concurrency",
"type": "integer",
"description": "Minimum number of parallel requests.",
"default": 1
},
"maxRequestRetries": {
"title": "Max request retries",
"type": "integer",
"description": "How many times to retry a failed request before giving up.",
"default": 8
},
"proxy": {
"title": "Proxy configuration (optional override)",
"type": "object",
"description": "Leave empty — the actor already routes all traffic through its own built-in residential proxy at no extra cost to you. Only set this if you want to use your own proxies."
}
}
},
"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
}
}
}
}
}
}
}
}
}
}