{
"openapi": "3.0.1",
"info": {
"title": "TikTok [only $0.9💰] Ad Library & Hashtag Trends Scraper",
"description": "💰$0.9 per 1,000 results. Unlock TikTok's viral potential with real-time hashtag analytics, audience insights, and trend data—transform raw metrics into winning strategies with precision-scraped engagement stats, demographic breakdowns, and competitive intelligence that keep you ahead in the game.",
"version": "0.0",
"x-build-id": "hO9WrauJ1SuLDT9xs"
},
"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"
},
"industry": {
"title": "Industry",
"enum": [
"all",
"22000000000",
"12000000000",
"14000000000",
"24000000000",
"10000000000",
"13000000000",
"27000000000",
"25000000000",
"29000000000",
"21000000000",
"18000000000",
"26000000000",
"23000000000",
"19000000000",
"28000000000",
"15000000000",
"17000000000",
"11000000000"
],
"type": "string",
"description": "Restrict trending hashtags to a single industry, or pick All to scrape every industry.",
"default": "all"
},
"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 in \"…\" for exact-phrase match. In Other Commercial Content mode, this searches creator username or brand name."
},
"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."
},
"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"
},
"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",
"enum": [
"for_you",
"ctr",
"play_2s_rate",
"play_6s_rate",
"cvr",
"like",
"impression",
"cost"
],
"type": "string",
"description": "How the top ads are ranked.",
"default": "for_you"
},
"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). 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)",
"enum": [
"",
"campaign_objective_traffic",
"campaign_objective_conversion",
"campaign_objective_reach",
"campaign_objective_app_install",
"campaign_objective_video_view",
"campaign_objective_lead_generation",
"campaign_objective_product_sales",
"campaign_objective_engagement"
],
"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 fetched ranking — TikTok's public Creative Center API has no server-side keyword search, so this filters results rather than querying TikTok. 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 fetched ranking (TikTok's public API exposes no like-tier filter). Example: 1000. Leave empty for no filter."
},
"extractDetails": {
"title": "Fetch full ad details",
"type": "boolean",
"description": "Top Ads: fetches each ad's detail endpoint for the complete field set (target country list, landing page, comments/shares, keyword list, objectives). Off = faster/cheaper, list-level fields only (CTR, cost, likes, video).
Ad Library: currently has no effect — TikTok signs its per-ad detail endpoint with a fresh browser-issued signature per ad, which this browser-free scraper cannot produce (every pure-HTTP attempt returns 421). Ad Library rows are therefore always search-level; audience targeting and per-country reach are not included. The run log says so explicitly when you enable it.",
"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. TikTok signs this endpoint per ad, so it is fetched by opening each ad in a real browser (about 2-3 seconds per ad) - noticeably slower, and 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
}
}
},
"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
}
}
}
}
}
}
}
}
}
}