{ "openapi": "3.0.1", "info": { "title": "Tiktok Trending Hashtags Analytics Scraper By Country", "description": "Scrape trending TikTok hashtags with detailed analytics, including views, growth, related tags, and top content insights. This actor delivers structured data for trend tracking, marketing research, and performance analysis in JSON or CSV formats.", "version": "0.1", "x-build-id": "WyINum8bA7FJueO5D" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scraper-engine~tiktok-trending-hashtags-analytics/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scraper-engine-tiktok-trending-hashtags-analytics", "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/scraper-engine~tiktok-trending-hashtags-analytics/runs": { "post": { "operationId": "runs-sync-scraper-engine-tiktok-trending-hashtags-analytics", "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/scraper-engine~tiktok-trending-hashtags-analytics/run-sync": { "post": { "operationId": "run-sync-scraper-engine-tiktok-trending-hashtags-analytics", "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": { "result_type": { "title": "๐ŸŽ›๏ธ Result type", "enum": [ "top100", "top100_with_analytics", "analytics" ], "type": "string", "description": "๐Ÿง  Output shape. โšก top100 = ranking only (analytics blob stays empty, exactly like the original actor). ๐ŸŽฏ top100_with_analytics = ranking + trend curve + top creators. ๐Ÿงช analytics = keep only the hashtags you name in 'Custom hashtag list' (now matched against the whole country sweep, not just one 3-row board).", "default": "top100_with_analytics" }, "country": { "title": "๐ŸŒ Country / region (single)", "enum": [ "ALL", "AL", "AR", "AT", "AU", "BD", "BE", "BG", "BH", "BR", "BY", "CA", "CH", "CL", "CN", "CO", "CZ", "DE", "DK", "EE", "EG", "ES", "FI", "FR", "GB", "GR", "HK", "HR", "HU", "ID", "IE", "IL", "IN", "IQ", "IS", "IT", "JO", "JP", "KH", "KR", "KW", "KZ", "LB", "LT", "LU", "LV", "MA", "MN", "MO", "MX", "MY", "NG", "NL", "NO", "NZ", "OM", "PE", "PH", "PK", "PL", "PT", "QA", "RO", "SA", "SE", "SG", "SK", "TH", "TR", "TW", "UA", "AE", "US", "UZ", "VN", "ZA" ], "type": "string", "description": "๐ŸŽช Single-country mode. Used when you leave 'Countries to sweep', 'Country preset' and 'Sweep all supported countries' untouched.\n\nโœ… Really supported by TikTok: US FR DE IT ES GB AR AU BR CA CO EG ID IL JP KR MY MX PH SA SG ZA TW TH TR AE VN.\nโš ๏ธ Every other value here โ€” including ๐ŸŒ ALL โ€” silently returns the United States board upstream. The actor accepts it, runs it, and marks the row with countrySupported=false + countryFallbackApplied=true instead of pretending.", "default": "US" }, "regions": { "title": "๐ŸŒŽ Countries to sweep", "type": "array", "description": "โœ… Multi-select of the 27 countries TikTok genuinely supports. Leave empty to fall back to 'Country preset', then 'Sweep all supported countries', then the single ๐ŸŒ Country field above.", "items": { "type": "string", "enum": [ "US", "GB", "CA", "AU", "FR", "DE", "IT", "ES", "BR", "MX", "AR", "CO", "JP", "KR", "TW", "TH", "VN", "PH", "MY", "SG", "ID", "AE", "SA", "EG", "IL", "TR", "ZA" ], "enumTitles": [ "๐Ÿ‡บ๐Ÿ‡ธ United States", "๐Ÿ‡ฌ๐Ÿ‡ง United Kingdom", "๐Ÿ‡จ๐Ÿ‡ฆ Canada", "๐Ÿ‡ฆ๐Ÿ‡บ Australia", "๐Ÿ‡ซ๐Ÿ‡ท France", "๐Ÿ‡ฉ๐Ÿ‡ช Germany", "๐Ÿ‡ฎ๐Ÿ‡น Italy", "๐Ÿ‡ช๐Ÿ‡ธ Spain", "๐Ÿ‡ง๐Ÿ‡ท Brazil", "๐Ÿ‡ฒ๐Ÿ‡ฝ Mexico", "๐Ÿ‡ฆ๐Ÿ‡ท Argentina", "๐Ÿ‡จ๐Ÿ‡ด Colombia", "๐Ÿ‡ฏ๐Ÿ‡ต Japan", "๐Ÿ‡ฐ๐Ÿ‡ท South Korea", "๐Ÿ‡น๐Ÿ‡ผ Taiwan", "๐Ÿ‡น๐Ÿ‡ญ Thailand", "๐Ÿ‡ป๐Ÿ‡ณ Vietnam", "๐Ÿ‡ต๐Ÿ‡ญ Philippines", "๐Ÿ‡ฒ๐Ÿ‡พ Malaysia", "๐Ÿ‡ธ๐Ÿ‡ฌ Singapore", "๐Ÿ‡ฎ๐Ÿ‡ฉ Indonesia", "๐Ÿ‡ฆ๐Ÿ‡ช United Arab Emirates", "๐Ÿ‡ธ๐Ÿ‡ฆ Saudi Arabia", "๐Ÿ‡ช๐Ÿ‡ฌ Egypt", "๐Ÿ‡ฎ๐Ÿ‡ฑ Israel", "๐Ÿ‡น๐Ÿ‡ท Tรผrkiye", "๐Ÿ‡ฟ๐Ÿ‡ฆ South Africa" ] }, "default": [] }, "regionPreset": { "title": "๐Ÿ—บ๏ธ Country preset", "enum": [ "none", "all_supported", "anglo", "europe", "latam", "apac", "mena" ], "type": "string", "description": "๐Ÿš€ One-click region bundles, built from the 27 supported countries only. Ignored when 'Countries to sweep' is filled in.", "default": "none" }, "allRegions": { "title": "๐ŸŒ Sweep all 27 supported countries", "type": "boolean", "description": "๐Ÿ”˜ Shortcut for the full country sweep. Overrides 'Countries to sweep' and 'Country preset'. 81 requests when combined with all three windows.", "default": false }, "windowDays": { "title": "๐Ÿ“… Time windows to sweep", "type": "array", "description": "โฑ๏ธ TikTok has exactly three real windows: 7, 30 and 90 days. Each returns a genuinely different 3-hashtag board. Leave empty to use the single ๐Ÿ† ranking period field below.\n\n๐Ÿ’ก 90 days is real upstream and is NOT offered by the original actor โ€” it is the deepest board TikTok will serve anonymously.", "items": { "type": "string", "enum": [ "7", "30", "90" ], "enumTitles": [ "๐Ÿ“† 7 days", "๐Ÿ“† 30 days", "๐Ÿ“† 90 days (deepest real window)" ] }, "default": [] }, "top100_period": { "title": "๐Ÿ† Ranking period (single window)", "enum": [ "7", "30", "90", "120" ], "type": "string", "description": "๐Ÿ•’ Used when 'Time windows to sweep' is empty.\n\nโœ… 7, 30 and 90 are real. โš ๏ธ 120 is kept for backwards compatibility but TikTok silently serves the 7-day board for it โ€” the actor reports periodAliasApplied=true and periodUsed=7 rather than mislabelling the data.", "default": "7" }, "analytics_period": { "title": "๐Ÿ“Š Hashtag analytics period (legacy, no effect)", "enum": [ "7", "30", "120", "365", "1095" ], "type": "string", "description": "๐Ÿงพ Kept so old run configurations keep working. Curve length is decided entirely by the ranking window โ€” this field has no upstream consumer, and 365/1095-day curves do not exist. Whatever you pick, the actor reports analyticsPeriodSupported=false and uses the real window.", "default": "30" }, "industryIn": { "title": "๐Ÿญ Keep only these industries", "type": "array", "description": "๐ŸŽฏ Client-side filter over the industry ids TikTok attaches to each hashtag. Leave empty to keep everything (and to fall back to the single ๐Ÿท๏ธ industry field below).\n\n๐Ÿ“ Measured on 243 live rows: 229 (94%) carry at least one industry id, and only 10 distinct industries ever appeared โ€” News & Entertainment and Sports & Outdoor alone are 75% of all rows. Industries TikTok never labels are reported as unsupported instead of silently zeroing your run.", "items": { "type": "string", "enum": [ "News & Entertainment", "Sports & Outdoor", "Games", "Apparel & Accessories", "Beauty & Personal Care", "Travel", "Food & Beverage", "Education", "Pets", "Financial Services", "Baby, Kids & Maternity", "Business Services", "Healthcare", "Home Improvement", "Household Products", "Life Services", "Real Estate", "Software & Apps", "Tech & Electronics", "Vehicle & Transportation" ], "enumTitles": [ "๐ŸŽฌ News & Entertainment โœ… (43% of rows)", "โšฝ Sports & Outdoor โœ… (32%)", "๐ŸŽฎ Games โœ… (12%)", "๐Ÿ‘— Apparel & Accessories โœ… (3%)", "๐Ÿ’„ Beauty & Personal Care โœ… (3%)", "โœˆ๏ธ Travel โœ… (2%)", "๐Ÿ” Food & Beverage โœ… (2%)", "๐Ÿ“š Education โœ… (1%)", "๐Ÿพ Pets โœ… (<1%)", "๐Ÿฆ Financial Services โœ… (<1%)", "๐Ÿ‘ถ Baby, Kids & Maternity (never observed)", "๐Ÿ’ผ Business Services (never observed)", "โš•๏ธ Healthcare (never observed)", "๐Ÿ”จ Home Improvement (never observed)", "๐Ÿงฝ Household Products (never observed)", "๐Ÿ›Ž๏ธ Life Services (never observed)", "๐Ÿ  Real Estate (never observed)", "๐Ÿ’ป Software & Apps (never observed)", "๐Ÿ“ฑ Tech & Electronics (never observed)", "๐Ÿš— Vehicle & Transportation (never observed)" ] }, "default": [] }, "top100_industry": { "title": "๐Ÿท๏ธ Industry filter (single, legacy)", "enum": [ "", "Apparel & Accessories", "Baby, Kids & Maternity", "Beauty & Personal Care", "Business Services", "Education", "Financial Services", "Food & Beverage", "Games", "Healthcare", "Home Improvement", "Household Products", "Life Services", "News & Entertainment", "Pets", "Real Estate", "Software & Apps", "Sports & Outdoor", "Tech & Electronics", "Travel", "Vehicle & Transportation" ], "type": "string", "description": "๐Ÿงฉ Single-industry version of the field above, kept for backwards compatibility. Used only when 'Keep only these industries' is empty. In the original actor this input did nothing at all; here it is a real client-side filter for the 10 industries TikTok actually labels.", "default": "" }, "top100_new_on_board": { "title": "โœจ New to the board only (not supported upstream)", "type": "boolean", "description": "๐Ÿ†• Kept for backwards compatibility. TikTok ignores every spelling of this flag (4 tested) and returns identical rows, and no 'new on board' marker exists in the payload. Turning it on sets newOnBoardSupported=false on every row rather than filtering nothing silently.", "default": false }, "hashtag_list": { "title": "๐Ÿ“ Custom hashtag list", "type": "array", "description": "๐ŸŽฏ Hashtag names without '#'. In ๐Ÿงช analytics mode only the hashtags you list are kept. Unlike the original actor, the names are matched against the ENTIRE country ร— window sweep (~150 unique tags on a full sweep), not against one 3-row board โ€” so far fewer of your names get dropped. Names still missing after the sweep are reported by name.", "default": [], "items": { "type": "string" } }, "total_hashtags": { "title": "๐Ÿ”ข Max hashtags to return", "minimum": 1, "maximum": 500, "type": "integer", "description": "๐ŸŽš๏ธ Cap on how many hashtag rows land in the dataset (1โ€“500).\n\nโš ๏ธ Reality check: TikTok serves exactly 3 hashtags per country + window (totalCount:3 on 81/81 slices measured today). A full 27-country ร— 3-window sweep yields ~150 unique hashtags โ€” that is the practical ceiling, so values above ~150 simply return everything the sweep found.", "default": 10 }, "includeRegionRollup": { "title": "๐Ÿงฎ Add cross-country rollup columns", "type": "boolean", "description": "๐Ÿ“ˆ Adds regionSpread, regionsTrendingIn, windowsTrendingIn, bestRank / bestRankRegion and the per-slice appearances[] breakdown. This is what turns 81 tiny boards into one answer: a hashtag trending in 9 countries at once is the signal you are buying.", "default": true }, "dedupeAcrossSlices": { "title": "๐Ÿงน One row per hashtag (dedupe across slices)", "type": "boolean", "description": "โœ… ON (recommended): one row per unique hashtag, merged across every country and window it appeared in, keeping its best rank as the headline. โŒ OFF: one row per hashtag per slice โ€” bigger and more repetitive, useful if you want the raw per-country boards.", "default": true }, "sweepConcurrency": { "title": "โšก Parallel slice requests", "minimum": 1, "maximum": 12, "type": "integer", "description": "๐ŸŽ๏ธ How many country ร— window requests run at once. 8 completed a full 81-slice sweep in ~7 seconds with zero rate-limiting in testing. Lower it if you route through a slow proxy.", "default": 8 }, "proxyConfiguration": { "title": "๐Ÿ›ก๏ธ Proxy configuration", "type": "object", "description": "๐ŸŽ›๏ธ Optional. Leave the default on; the actor still tries direct first because that is what tested fastest and cleanest. The proxy is the fallback path if a direct request is refused.", "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 } } }, "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 } } } } } } } } } }