{ "data": { "id": "vB58tHp5oGWTEgfzB", "actId": "yVYeUmb7hb4vybt1d", "userId": "zq8lKbpLzTjGDayPC", "startedAt": "2026-10-19T20:51:13.857Z", "finishedAt": "2026-10-19T20:51:55.256Z", "status": "SUCCEEDED", "meta": { "origin": "CLI" }, "stats": { "durationMillis": 41304, "runTimeSecs": 41.304, "computeUnits": 0.045893333333333335, "imageSizeBytes": 3099659264 }, "options": { "useCache": true, "betaPackages": false, "memoryMbytes": 4096, "diskMbytes": 8192 }, "createdByOrganizationMemberUserId": "GK9YjZRyQZVzOdoH5", "exitCode": 0, "inputSchema": "{\n \"title\": \"TikTok Hashtag Momentum & Top Creator Tracker Input\",\n \"description\": \"Collect TikTok's ranked trending hashtags and trending videos by market, time window and industry, with post/view counts, popularity curves, momentum signals, creator leaders and video engagement metrics. No login, cookies or proxy setup.\",\n \"type\": \"object\",\n \"schemaVersion\": 1,\n \"properties\": {\n \"mode\": {\n \"title\": \"What to collect\",\n \"type\": \"string\",\n \"description\": \"Choose 'Trending hashtags' for TikTok's ranked hashtag charts (post/view counts, popularity curve, creators) or 'Trending videos' for TikTok's ranked video charts (views, engagement, author stats).\",\n \"editor\": \"select\",\n \"enum\": [\n \"trendingHashtags\",\n \"trendingVideos\"\n ],\n \"enumTitles\": [\n \"Trending hashtags\",\n \"Trending videos\"\n ],\n \"default\": \"trendingHashtags\",\n \"prefill\": \"trendingHashtags\"\n },\n \"countries\": {\n \"title\": \"Markets\",\n \"type\": \"array\",\n \"description\": \"(mode=trendingHashtags) One or more markets to read the hashtag chart for. Each market adds its own ranked rows.\",\n \"editor\": \"select\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"US\",\n \"GB\",\n \"CA\",\n \"AU\",\n \"DE\",\n \"FR\",\n \"IT\",\n \"ES\",\n \"BR\",\n \"MX\",\n \"AR\",\n \"CO\",\n \"JP\",\n \"KR\",\n \"ID\",\n \"MY\",\n \"PH\",\n \"SG\",\n \"TH\",\n \"VN\",\n \"TW\",\n \"TR\",\n \"SA\",\n \"AE\",\n \"IL\",\n \"EG\",\n \"ZA\"\n ],\n \"enumTitles\": [\n \"United States\",\n \"United Kingdom\",\n \"Canada\",\n \"Australia\",\n \"Germany\",\n \"France\",\n \"Italy\",\n \"Spain\",\n \"Brazil\",\n \"Mexico\",\n \"Argentina\",\n \"Colombia\",\n \"Japan\",\n \"South Korea\",\n \"Indonesia\",\n \"Malaysia\",\n \"Philippines\",\n \"Singapore\",\n \"Thailand\",\n \"Vietnam\",\n \"Taiwan\",\n \"Turkey\",\n \"Saudi Arabia\",\n \"United Arab Emirates\",\n \"Israel\",\n \"Egypt\",\n \"South Africa\"\n ]\n },\n \"default\": [\n \"US\"\n ],\n \"prefill\": [\n \"US\"\n ]\n },\n \"periods\": {\n \"title\": \"Time Windows\",\n \"type\": \"array\",\n \"description\": \"(mode=trendingHashtags) Lookback windows in days. 7 shows recent spikes, 90 shows longer-term trends. Select one or more.\",\n \"editor\": \"select\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"7\",\n \"30\",\n \"90\"\n ],\n \"enumTitles\": [\n \"Last 7 days\",\n \"Last 30 days\",\n \"Last 90 days\"\n ]\n },\n \"default\": [\n \"7\"\n ],\n \"prefill\": [\n \"7\"\n ]\n },\n \"includeOverallRanking\": {\n \"title\": \"Include Overall Chart\",\n \"type\": \"boolean\",\n \"description\": \"(mode=trendingHashtags) Include each market's overall top-3 hashtag chart. Turn off to read only the industry charts selected below.\",\n \"default\": true,\n \"prefill\": true\n },\n \"scanAllIndustries\": {\n \"title\": \"Scan All Industries\",\n \"type\": \"boolean\",\n \"description\": \"(mode=trendingHashtags) Read all 19 industry charts for every market and window. This widens coverage from 3 to up to 60 hashtags per market and window, because each industry chart is read separately.\",\n \"default\": true,\n \"prefill\": false\n },\n \"industries\": {\n \"title\": \"Industry Charts\",\n \"type\": \"array\",\n \"description\": \"(mode=trendingHashtags) Specific industry charts to read when 'Scan all industries' is off. Ignored when scanning all industries. 19 public categories are available.\",\n \"editor\": \"select\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"10000000000\",\n \"11000000000\",\n \"12000000000\",\n \"13000000000\",\n \"14000000000\",\n \"15000000000\",\n \"16000000000\",\n \"17000000000\",\n \"18000000000\",\n \"19000000000\",\n \"20000000000\",\n \"21000000000\",\n \"22000000000\",\n \"23000000000\",\n \"24000000000\",\n \"25000000000\",\n \"27000000000\",\n \"28000000000\",\n \"29000000000\"\n ],\n \"enumTitles\": [\n \"Education\",\n \"Vehicle & Transportation\",\n \"Baby, Kids & Maternity\",\n \"Financial Services\",\n \"Beauty & Personal Care\",\n \"Tech & Electronics\",\n \"Appliances\",\n \"Travel\",\n \"Household Products\",\n \"Pets\",\n \"Apps\",\n \"Home Improvement\",\n \"Apparel & Accessories\",\n \"News & Entertainment\",\n \"Business Services\",\n \"Games\",\n \"Food & Beverage\",\n \"Sports & Outdoor\",\n \"Health\"\n ]\n },\n \"default\": [],\n \"prefill\": []\n },\n \"includeCreatorLeaders\": {\n \"title\": \"Add Creator Leaderboard\",\n \"type\": \"boolean\",\n \"description\": \"(mode=trendingHashtags) Add creator rows that aggregate the creators TikTok credits across the collected hashtags, sorted by how many trends they appear in.\",\n \"default\": false,\n \"prefill\": false\n },\n \"minHashtagAppearances\": {\n \"title\": \"Minimum Trend Appearances\",\n \"type\": \"integer\",\n \"description\": \"(mode=trendingHashtags, creator leaderboard only) Only list creators credited on at least this many collected hashtag rows.\",\n \"default\": 2,\n \"minimum\": 1,\n \"maximum\": 10,\n \"prefill\": 2\n },\n \"videoCountries\": {\n \"title\": \"Video Markets\",\n \"type\": \"array\",\n \"description\": \"(mode=trendingVideos) Markets with a public TikTok trending-video chart. Select one or more.\",\n \"editor\": \"select\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"US\",\n \"JP\",\n \"VN\",\n \"TH\",\n \"ID\"\n ],\n \"enumTitles\": [\n \"United States\",\n \"Japan\",\n \"Vietnam\",\n \"Thailand\",\n \"Indonesia\"\n ]\n },\n \"default\": [\n \"US\"\n ],\n \"prefill\": [\n \"US\"\n ]\n },\n \"videoPeriods\": {\n \"title\": \"Video Time Windows\",\n \"type\": \"array\",\n \"description\": \"(mode=trendingVideos) Windows in days for the trending-video chart: 7 for videos created in the last week, 30 for the last month.\",\n \"editor\": \"select\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"7\",\n \"30\"\n ],\n \"enumTitles\": [\n \"Last 7 days\",\n \"Last 30 days\"\n ]\n },\n \"default\": [\n \"7\"\n ],\n \"prefill\": [\n \"7\"\n ]\n },\n \"videoSortBy\": {\n \"title\": \"Rank Videos By\",\n \"type\": \"string\",\n \"description\": \"(mode=trendingVideos) Metric used for the video ranking.\",\n \"editor\": \"select\",\n \"enum\": [\n \"views\",\n \"engagementRate\",\n \"sixSecondViewRate\"\n ],\n \"enumTitles\": [\n \"Video views\",\n \"Engagement rate\",\n \"6-second view-through rate\"\n ],\n \"default\": \"views\",\n \"prefill\": \"views\"\n },\n \"videoOrganicOnly\": {\n \"title\": \"Organic Videos Only\",\n \"type\": \"boolean\",\n \"description\": \"(mode=trendingVideos) Rank only organic (non-promoted) videos. TikTok returns a different ranking for organic-only charts.\",\n \"default\": false,\n \"prefill\": false\n },\n \"videoContentTags\": {\n \"title\": \"Video Content Tags\",\n \"type\": \"array\",\n \"description\": \"(mode=trendingVideos) Query TikTok's video ranking by content tag and dedupe the videos. Each selected tag is a separate ranking read; 'All tags' also includes the unfiltered chart, returning up to ~24 videos per market, window and sort instead of 4. Leave empty for the current unfiltered ranking.\",\n \"editor\": \"select\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"all\",\n \"11002\",\n \"11003\",\n \"11010\",\n \"11013\",\n \"11015\"\n ],\n \"enumTitles\": [\n \"All tags (unfiltered + 5 tags)\",\n \"Beauty & Care\",\n \"Fashion\",\n \"Food & Beverage\",\n \"Lifestyle & Leisure\",\n \"Technology & Finance\"\n ]\n },\n \"default\": [],\n \"prefill\": []\n },\n \"weeksBack\": {\n \"title\": \"Extra Weekly Windows\",\n \"type\": \"integer\",\n \"description\": \"(mode=trendingVideos) Add past weekly rankings by moving the chart end date back 7 days per step (0-4). Useful for comparing this week with earlier weeks.\",\n \"default\": 0,\n \"minimum\": 0,\n \"maximum\": 4,\n \"prefill\": 0\n },\n \"includeTopComments\": {\n \"title\": \"Include Top Comments\",\n \"type\": \"boolean\",\n \"description\": \"(mode=trendingVideos) Add each video's top comments and comment keywords. Each video's comments are read separately (up to 100 videos per run).\",\n \"default\": false,\n \"prefill\": false\n },\n \"maxItems\": {\n \"title\": \"Maximum Rows\",\n \"type\": \"integer\",\n \"description\": \"Maximum number of data rows to write per run. Creator rows are not counted.\",\n \"default\": 1000,\n \"minimum\": 1,\n \"maximum\": 5000,\n \"prefill\": 10\n }\n },\n \"required\": []\n}", "readme": "# TikTok Hashtag Momentum & Top Creator Tracker\n\nRead TikTok's own ranked trending-hashtag and trending-video charts from the public Creative Center. For every market you choose, this actor returns exact post and view counts, a day-by-day popularity curve, a plain-language momentum read (rising, peaking, fading), the creators TikTok credits for each trend, and — when you ask for videos — the engagement metrics behind what is winning right now. No TikTok login, cookies or proxy setup.\n\n## What this actor does\n\n- **Two collections:** `trendingHashtags` reads TikTok's ranked hashtag charts; `trendingVideos` reads its ranked trending-video charts.\n- **27 hashtag markets, 3 windows:** pick any mix of 27 markets and 7/30/90-day windows. The overall chart plus all 19 industry charts are available, widening one market/window from 3 hashtags to up to 60.\n- **Momentum, not just a snapshot:** every hashtag carries TikTok's daily popularity curve plus a derived momentum score, trend direction, trend stage, peak date and volatility.\n- **Creator leaders:** every trending hashtag includes TikTok's top-3 credited creators; an optional leaderboard aggregates them across the whole run so you can see who keeps appearing.\n- **Trending videos:** five markets with public video charts, ranked by views, engagement rate or 6-second view-through rate, with author followers, lifetime metrics and optional top comments. Content-tag rankings (Beauty & Care, Fashion, Food & Beverage, Lifestyle & Leisure, Technology & Finance) can be queried individually or all at once, deduping videos for up to ~24 per market/window/sort instead of 4.\n- **Honest caps:** TikTok's public charts show 3 hashtags per ranking and 4 videos per video ranking to guests. The actor explains its coverage in the run status instead of implying more.\n- Empty fields are omitted — never returned as `null`, `\"\"` or `[]`.\n\n## Output per hashtag (`rowType: \"hashtag\"`)\n\n- `hashtagId`, `hashtagName`, `hashtagUrl` — identity and the durable tag page link\n- `rankIndex`, `isOverallRanking`, `rankingSlices` — rank, whether it made the overall chart, and which industry charts it also ranked in\n- `publishCnt` — posts published with the hashtag during the window\n- `vv` — total video views those posts earned during the window\n- `avgViewsPerPost` — views divided by posts\n- `popularityCurve` — daily `{date, value}` points from TikTok's normalized 0–100 index\n- `momentumChangePct`, `trendDirection`, `trendStage`, `peakDate`, `peakValue`, `curveVolatility` — derived momentum signals\n- `industryIds`, `industryNames` — TikTok's category tags for the hashtag\n- `topCreators[]` — TikTok's credited creators (`rank`, `ttuid`, `handleName`, `nickname`, `followerCount`, `countryCode`, `avatarUrl`)\n- `observedCountry`, `observedPeriod`, `scrapedAt`, `dataSource`\n\n## Output per creator (`rowType: \"creator\"`, optional)\n\n- `creatorId`, `handleName`, `nickname`, `followerCount`, `countryCode`, `avatarUrl`\n- `appearances` — how many collected hashtag rows credited this creator\n- `hashtags[]`, `bestRank`, `observedCountries[]`, `observedPeriods[]`, `scrapedAt`\n\n## Output per video (`rowType: \"video\"`)\n\n- `videoId`, `videoUrl`, `embedUrl`, `caption`, `hashtags[]`\n- `createTime`, `createdAt`, `ageDays`, `coverUrl`\n- `author` — `id`, `username`, `displayName`, `bio`, `followerCount`, `avatarUrl`\n- `views`, `organicViews`, `engagementRate`, `sixSecondViewRate` — window metrics\n- `viewsLifeTime`, `organicViewsLifeTime`, `engagementRateLifeTime`, `sixSecondViewRateLifeTime` — lifetime metrics\n- `viewsPerDay`, `lifetimeViewsShare` — derived velocity\n- `topComments[]`, `commentKeywords[]` — only with Include top comments\n- `contentTag` — the content-tag ranking that surfaced this video (omitted for the unfiltered ranking)\n- `rankingKey` — provenance key: `market:window:sort:weeksBack:tag` (`all` = unfiltered)\n- `observedCountry`, `observedPeriod`, `videoSortBy`, `weeksBack`, `scrapedAt`\n\n## Input\n\n| Field | Type | Default | Description |\n|---|---|---|---|\n| `mode` | select | `trendingHashtags` | `trendingHashtags` or `trendingVideos` |\n| `countries` | multi-select | `[\"US\"]` | 27 markets for the hashtag chart |\n| `periods` | multi-select | `[\"7\"]` | Hashtag windows: 7 / 30 / 90 days |\n| `includeOverallRanking` | boolean | `true` | Include each market's overall top-3 chart |\n| `scanAllIndustries` | boolean | `true` | Read all 19 industry charts (up to 60 hashtags per market/window) |\n| `industries` | multi-select | `[]` | Specific industry charts when `scanAllIndustries` is off |\n| `includeCreatorLeaders` | boolean | `false` | Emit the aggregated creator leaderboard |\n| `minHashtagAppearances` | integer | `2` | Minimum trend appearances for a creator row |\n| `videoCountries` | multi-select | `[\"US\"]` | Video chart markets: US, JP, VN, TH, ID |\n| `videoPeriods` | multi-select | `[\"7\"]` | Video windows: 7 / 30 days |\n| `videoSortBy` | select | `views` | `views`, `engagementRate`, `sixSecondViewRate` |\n| `videoOrganicOnly` | boolean | `false` | Rank only organic (non-promoted) videos |\n| `videoContentTags` | multi-select | `[]` | Content-tag rankings; each selected tag is a separate ranking read, deduped by video. `all` = unfiltered + all five tags |\n| `weeksBack` | integer | `0` | Extra past weekly video rankings (0–4) |\n| `includeTopComments` | boolean | `false` | Add top comments and keywords (up to 100 videos) |\n| `maxItems` | integer | `1000` | Maximum hashtag/video rows per run |\n\n### Example: this week's US hashtags, every industry\n\n```json\n{\n \"mode\": \"trendingHashtags\",\n \"countries\": [\"US\"],\n \"periods\": [\"7\"],\n \"scanAllIndustries\": true,\n \"includeCreatorLeaders\": true\n}\n```\n\n### Example: compare three markets over 30 days\n\n```json\n{\n \"mode\": \"trendingHashtags\",\n \"countries\": [\"US\", \"GB\", \"JP\"],\n \"periods\": [\"30\"],\n \"industries\": [\"14000000000\", \"27000000000\"],\n \"includeOverallRanking\": false\n}\n```\n\n### Example: trending videos in Japan and the US\n\n```json\n{\n \"mode\": \"trendingVideos\",\n \"videoCountries\": [\"US\", \"JP\"],\n \"videoPeriods\": [\"7\"],\n \"videoSortBy\": \"engagementRate\",\n \"weeksBack\": 2,\n \"includeTopComments\": true\n}\n```\n\n## Use cases\n\n- **Content calendars** — slot a market's current hashtags, with trend stage, into next week's posting plan.\n- **Trend timing** — separate hashtags that are still breaking from ones that already peaked.\n- **Creator partnerships** — see which creators TikTok credits across several rising trends before reaching out.\n- **Market comparison** — run the same window across markets to find local trends rather than global noise.\n- **Brand and campaign monitoring** — schedule a daily run and watch your tag enter, climb or leave a market's chart.\n- **Video performance research** — study the engagement rate and 6-second view-through rate of videos TikTok is surfacing right now.\n\n## FAQ\n\n**Why does one market return only a few hashtags?**\nTikTok's public Creative Center charts show the top 3 hashtags per ranking to visitors who are not signed in. This actor reads the overall chart plus the 19 industry charts, so a market and window yields up to 60 hashtags in total. There is no public path to a deeper ranking without a TikTok account.\n\n**What does the momentum score mean?**\n`momentumChangePct` compares the average of the most recent third of the popularity curve with the average of the third before it. It is a percentage of TikTok's normalized 0–100 index, not raw views. Values of +10% or more are labelled rising, -10% or less falling.\n\n**Why are video charts limited to five markets?**\nTikTok publishes trending-video charts publicly for the United States, Japan, Vietnam, Thailand and Indonesia. Hashtag charts cover 27 markets. The input lists exactly the markets that return video data.\n\n**How many videos can one ranking return?**\nThe public video chart shows 4 videos per market, window and sort. Adding extra weekly windows or selecting several markets or windows widens coverage; rows are deduplicated by video.\n\n**Why are comments optional?**\nTop comments are read separately for each video, so they are opt-in and capped at 100 videos per run.\n\n**Are the image links permanent?**\n`coverUrl` and creator `avatarUrl` are signed TikTok CDN links that expire after about 48 hours. The durable links are `videoUrl`, `embedUrl` and `hashtagUrl`, which always resolve.\n\n**Why do some hashtags have no industry?**\nTikTok assigns industry categories to only some hashtags. When it publishes none, `industryIds` and `industryNames` are omitted for that row.\n\n**Does this actor need cookies or a proxy?**\nNo. It reads TikTok's public Creative Center data over plain HTTP. There is nothing to log in to and no proxy to configure.\n\n**How fresh is the data?**\nThe charts refresh continuously. For trend tracking, schedule one run per market per day; repeated runs at the same time return the same ranking.\n\n**Is this affiliated with TikTok?**\nNo. This is a third-party actor that reads publicly available Creative Center trend data; it is not affiliated with TikTok or ByteDance.\n", "actorDefinition": { "actorSpecification": 1, "name": "tiktok-hashtag-momentum-and-top-creator-tracker", "title": "TikTok Hashtag Momentum & Top Creator Tracker", "description": "Reads TikTok Creative Center's ranked hashtag and video charts for 27 markets: exact post and view counts, popularity curves and momentum signals, top creators, and trending-video engagement metrics. No login or proxy setup.", "version": "1.0", "readme": "# TikTok Hashtag Momentum & Top Creator Tracker\n\nRead TikTok's own ranked trending-hashtag and trending-video charts from the public Creative Center. For every market you choose, this actor returns exact post and view counts, a day-by-day popularity curve, a plain-language momentum read (rising, peaking, fading), the creators TikTok credits for each trend, and — when you ask for videos — the engagement metrics behind what is winning right now. No TikTok login, cookies or proxy setup.\n\n## What this actor does\n\n- **Two collections:** `trendingHashtags` reads TikTok's ranked hashtag charts; `trendingVideos` reads its ranked trending-video charts.\n- **27 hashtag markets, 3 windows:** pick any mix of 27 markets and 7/30/90-day windows. The overall chart plus all 19 industry charts are available, widening one market/window from 3 hashtags to up to 60.\n- **Momentum, not just a snapshot:** every hashtag carries TikTok's daily popularity curve plus a derived momentum score, trend direction, trend stage, peak date and volatility.\n- **Creator leaders:** every trending hashtag includes TikTok's top-3 credited creators; an optional leaderboard aggregates them across the whole run so you can see who keeps appearing.\n- **Trending videos:** five markets with public video charts, ranked by views, engagement rate or 6-second view-through rate, with author followers, lifetime metrics and optional top comments. Content-tag rankings (Beauty & Care, Fashion, Food & Beverage, Lifestyle & Leisure, Technology & Finance) can be queried individually or all at once, deduping videos for up to ~24 per market/window/sort instead of 4.\n- **Honest caps:** TikTok's public charts show 3 hashtags per ranking and 4 videos per video ranking to guests. The actor explains its coverage in the run status instead of implying more.\n- Empty fields are omitted — never returned as `null`, `\"\"` or `[]`.\n\n## Output per hashtag (`rowType: \"hashtag\"`)\n\n- `hashtagId`, `hashtagName`, `hashtagUrl` — identity and the durable tag page link\n- `rankIndex`, `isOverallRanking`, `rankingSlices` — rank, whether it made the overall chart, and which industry charts it also ranked in\n- `publishCnt` — posts published with the hashtag during the window\n- `vv` — total video views those posts earned during the window\n- `avgViewsPerPost` — views divided by posts\n- `popularityCurve` — daily `{date, value}` points from TikTok's normalized 0–100 index\n- `momentumChangePct`, `trendDirection`, `trendStage`, `peakDate`, `peakValue`, `curveVolatility` — derived momentum signals\n- `industryIds`, `industryNames` — TikTok's category tags for the hashtag\n- `topCreators[]` — TikTok's credited creators (`rank`, `ttuid`, `handleName`, `nickname`, `followerCount`, `countryCode`, `avatarUrl`)\n- `observedCountry`, `observedPeriod`, `scrapedAt`, `dataSource`\n\n## Output per creator (`rowType: \"creator\"`, optional)\n\n- `creatorId`, `handleName`, `nickname`, `followerCount`, `countryCode`, `avatarUrl`\n- `appearances` — how many collected hashtag rows credited this creator\n- `hashtags[]`, `bestRank`, `observedCountries[]`, `observedPeriods[]`, `scrapedAt`\n\n## Output per video (`rowType: \"video\"`)\n\n- `videoId`, `videoUrl`, `embedUrl`, `caption`, `hashtags[]`\n- `createTime`, `createdAt`, `ageDays`, `coverUrl`\n- `author` — `id`, `username`, `displayName`, `bio`, `followerCount`, `avatarUrl`\n- `views`, `organicViews`, `engagementRate`, `sixSecondViewRate` — window metrics\n- `viewsLifeTime`, `organicViewsLifeTime`, `engagementRateLifeTime`, `sixSecondViewRateLifeTime` — lifetime metrics\n- `viewsPerDay`, `lifetimeViewsShare` — derived velocity\n- `topComments[]`, `commentKeywords[]` — only with Include top comments\n- `contentTag` — the content-tag ranking that surfaced this video (omitted for the unfiltered ranking)\n- `rankingKey` — provenance key: `market:window:sort:weeksBack:tag` (`all` = unfiltered)\n- `observedCountry`, `observedPeriod`, `videoSortBy`, `weeksBack`, `scrapedAt`\n\n## Input\n\n| Field | Type | Default | Description |\n|---|---|---|---|\n| `mode` | select | `trendingHashtags` | `trendingHashtags` or `trendingVideos` |\n| `countries` | multi-select | `[\"US\"]` | 27 markets for the hashtag chart |\n| `periods` | multi-select | `[\"7\"]` | Hashtag windows: 7 / 30 / 90 days |\n| `includeOverallRanking` | boolean | `true` | Include each market's overall top-3 chart |\n| `scanAllIndustries` | boolean | `true` | Read all 19 industry charts (up to 60 hashtags per market/window) |\n| `industries` | multi-select | `[]` | Specific industry charts when `scanAllIndustries` is off |\n| `includeCreatorLeaders` | boolean | `false` | Emit the aggregated creator leaderboard |\n| `minHashtagAppearances` | integer | `2` | Minimum trend appearances for a creator row |\n| `videoCountries` | multi-select | `[\"US\"]` | Video chart markets: US, JP, VN, TH, ID |\n| `videoPeriods` | multi-select | `[\"7\"]` | Video windows: 7 / 30 days |\n| `videoSortBy` | select | `views` | `views`, `engagementRate`, `sixSecondViewRate` |\n| `videoOrganicOnly` | boolean | `false` | Rank only organic (non-promoted) videos |\n| `videoContentTags` | multi-select | `[]` | Content-tag rankings; each selected tag is a separate ranking read, deduped by video. `all` = unfiltered + all five tags |\n| `weeksBack` | integer | `0` | Extra past weekly video rankings (0–4) |\n| `includeTopComments` | boolean | `false` | Add top comments and keywords (up to 100 videos) |\n| `maxItems` | integer | `1000` | Maximum hashtag/video rows per run |\n\n### Example: this week's US hashtags, every industry\n\n```json\n{\n \"mode\": \"trendingHashtags\",\n \"countries\": [\"US\"],\n \"periods\": [\"7\"],\n \"scanAllIndustries\": true,\n \"includeCreatorLeaders\": true\n}\n```\n\n### Example: compare three markets over 30 days\n\n```json\n{\n \"mode\": \"trendingHashtags\",\n \"countries\": [\"US\", \"GB\", \"JP\"],\n \"periods\": [\"30\"],\n \"industries\": [\"14000000000\", \"27000000000\"],\n \"includeOverallRanking\": false\n}\n```\n\n### Example: trending videos in Japan and the US\n\n```json\n{\n \"mode\": \"trendingVideos\",\n \"videoCountries\": [\"US\", \"JP\"],\n \"videoPeriods\": [\"7\"],\n \"videoSortBy\": \"engagementRate\",\n \"weeksBack\": 2,\n \"includeTopComments\": true\n}\n```\n\n## Use cases\n\n- **Content calendars** — slot a market's current hashtags, with trend stage, into next week's posting plan.\n- **Trend timing** — separate hashtags that are still breaking from ones that already peaked.\n- **Creator partnerships** — see which creators TikTok credits across several rising trends before reaching out.\n- **Market comparison** — run the same window across markets to find local trends rather than global noise.\n- **Brand and campaign monitoring** — schedule a daily run and watch your tag enter, climb or leave a market's chart.\n- **Video performance research** — study the engagement rate and 6-second view-through rate of videos TikTok is surfacing right now.\n\n## FAQ\n\n**Why does one market return only a few hashtags?**\nTikTok's public Creative Center charts show the top 3 hashtags per ranking to visitors who are not signed in. This actor reads the overall chart plus the 19 industry charts, so a market and window yields up to 60 hashtags in total. There is no public path to a deeper ranking without a TikTok account.\n\n**What does the momentum score mean?**\n`momentumChangePct` compares the average of the most recent third of the popularity curve with the average of the third before it. It is a percentage of TikTok's normalized 0–100 index, not raw views. Values of +10% or more are labelled rising, -10% or less falling.\n\n**Why are video charts limited to five markets?**\nTikTok publishes trending-video charts publicly for the United States, Japan, Vietnam, Thailand and Indonesia. Hashtag charts cover 27 markets. The input lists exactly the markets that return video data.\n\n**How many videos can one ranking return?**\nThe public video chart shows 4 videos per market, window and sort. Adding extra weekly windows or selecting several markets or windows widens coverage; rows are deduplicated by video.\n\n**Why are comments optional?**\nTop comments are read separately for each video, so they are opt-in and capped at 100 videos per run.\n\n**Are the image links permanent?**\n`coverUrl` and creator `avatarUrl` are signed TikTok CDN links that expire after about 48 hours. The durable links are `videoUrl`, `embedUrl` and `hashtagUrl`, which always resolve.\n\n**Why do some hashtags have no industry?**\nTikTok assigns industry categories to only some hashtags. When it publishes none, `industryIds` and `industryNames` are omitted for that row.\n\n**Does this actor need cookies or a proxy?**\nNo. It reads TikTok's public Creative Center data over plain HTTP. There is nothing to log in to and no proxy to configure.\n\n**How fresh is the data?**\nThe charts refresh continuously. For trend tracking, schedule one run per market per day; repeated runs at the same time return the same ranking.\n\n**Is this affiliated with TikTok?**\nNo. This is a third-party actor that reads publicly available Creative Center trend data; it is not affiliated with TikTok or ByteDance.\n", "meta": { "templateId": "python-httpx" }, "input": { "title": "TikTok Hashtag Momentum & Top Creator Tracker Input", "description": "Collect TikTok's ranked trending hashtags and trending videos by market, time window and industry, with post/view counts, popularity curves, momentum signals, creator leaders and video engagement metrics. No login, cookies or proxy setup.", "type": "object", "schemaVersion": 1, "properties": { "mode": { "title": "What to collect", "type": "string", "description": "Choose 'Trending hashtags' for TikTok's ranked hashtag charts (post/view counts, popularity curve, creators) or 'Trending videos' for TikTok's ranked video charts (views, engagement, author stats).", "editor": "select", "enum": [ "trendingHashtags", "trendingVideos" ], "enumTitles": [ "Trending hashtags", "Trending videos" ], "default": "trendingHashtags", "prefill": "trendingHashtags" }, "countries": { "title": "Markets", "type": "array", "description": "(mode=trendingHashtags) One or more markets to read the hashtag chart for. Each market adds its own ranked rows.", "editor": "select", "items": { "type": "string", "enum": [ "US", "GB", "CA", "AU", "DE", "FR", "IT", "ES", "BR", "MX", "AR", "CO", "JP", "KR", "ID", "MY", "PH", "SG", "TH", "VN", "TW", "TR", "SA", "AE", "IL", "EG", "ZA" ], "enumTitles": [ "United States", "United Kingdom", "Canada", "Australia", "Germany", "France", "Italy", "Spain", "Brazil", "Mexico", "Argentina", "Colombia", "Japan", "South Korea", "Indonesia", "Malaysia", "Philippines", "Singapore", "Thailand", "Vietnam", "Taiwan", "Turkey", "Saudi Arabia", "United Arab Emirates", "Israel", "Egypt", "South Africa" ] }, "default": [ "US" ], "prefill": [ "US" ] }, "periods": { "title": "Time Windows", "type": "array", "description": "(mode=trendingHashtags) Lookback windows in days. 7 shows recent spikes, 90 shows longer-term trends. Select one or more.", "editor": "select", "items": { "type": "string", "enum": [ "7", "30", "90" ], "enumTitles": [ "Last 7 days", "Last 30 days", "Last 90 days" ] }, "default": [ "7" ], "prefill": [ "7" ] }, "includeOverallRanking": { "title": "Include Overall Chart", "type": "boolean", "description": "(mode=trendingHashtags) Include each market's overall top-3 hashtag chart. Turn off to read only the industry charts selected below.", "default": true, "prefill": true }, "scanAllIndustries": { "title": "Scan All Industries", "type": "boolean", "description": "(mode=trendingHashtags) Read all 19 industry charts for every market and window. This widens coverage from 3 to up to 60 hashtags per market and window, because each industry chart is read separately.", "default": true, "prefill": false }, "industries": { "title": "Industry Charts", "type": "array", "description": "(mode=trendingHashtags) Specific industry charts to read when 'Scan all industries' is off. Ignored when scanning all industries. 19 public categories are available.", "editor": "select", "items": { "type": "string", "enum": [ "10000000000", "11000000000", "12000000000", "13000000000", "14000000000", "15000000000", "16000000000", "17000000000", "18000000000", "19000000000", "20000000000", "21000000000", "22000000000", "23000000000", "24000000000", "25000000000", "27000000000", "28000000000", "29000000000" ], "enumTitles": [ "Education", "Vehicle & Transportation", "Baby, Kids & Maternity", "Financial Services", "Beauty & Personal Care", "Tech & Electronics", "Appliances", "Travel", "Household Products", "Pets", "Apps", "Home Improvement", "Apparel & Accessories", "News & Entertainment", "Business Services", "Games", "Food & Beverage", "Sports & Outdoor", "Health" ] }, "default": [], "prefill": [] }, "includeCreatorLeaders": { "title": "Add Creator Leaderboard", "type": "boolean", "description": "(mode=trendingHashtags) Add creator rows that aggregate the creators TikTok credits across the collected hashtags, sorted by how many trends they appear in.", "default": false, "prefill": false }, "minHashtagAppearances": { "title": "Minimum Trend Appearances", "type": "integer", "description": "(mode=trendingHashtags, creator leaderboard only) Only list creators credited on at least this many collected hashtag rows.", "default": 2, "minimum": 1, "maximum": 10, "prefill": 2 }, "videoCountries": { "title": "Video Markets", "type": "array", "description": "(mode=trendingVideos) Markets with a public TikTok trending-video chart. Select one or more.", "editor": "select", "items": { "type": "string", "enum": [ "US", "JP", "VN", "TH", "ID" ], "enumTitles": [ "United States", "Japan", "Vietnam", "Thailand", "Indonesia" ] }, "default": [ "US" ], "prefill": [ "US" ] }, "videoPeriods": { "title": "Video Time Windows", "type": "array", "description": "(mode=trendingVideos) Windows in days for the trending-video chart: 7 for videos created in the last week, 30 for the last month.", "editor": "select", "items": { "type": "string", "enum": [ "7", "30" ], "enumTitles": [ "Last 7 days", "Last 30 days" ] }, "default": [ "7" ], "prefill": [ "7" ] }, "videoSortBy": { "title": "Rank Videos By", "type": "string", "description": "(mode=trendingVideos) Metric used for the video ranking.", "editor": "select", "enum": [ "views", "engagementRate", "sixSecondViewRate" ], "enumTitles": [ "Video views", "Engagement rate", "6-second view-through rate" ], "default": "views", "prefill": "views" }, "videoOrganicOnly": { "title": "Organic Videos Only", "type": "boolean", "description": "(mode=trendingVideos) Rank only organic (non-promoted) videos. TikTok returns a different ranking for organic-only charts.", "default": false, "prefill": false }, "videoContentTags": { "title": "Video Content Tags", "type": "array", "description": "(mode=trendingVideos) Query TikTok's video ranking by content tag and dedupe the videos. Each selected tag is a separate ranking read; 'All tags' also includes the unfiltered chart, returning up to ~24 videos per market, window and sort instead of 4. Leave empty for the current unfiltered ranking.", "editor": "select", "items": { "type": "string", "enum": [ "all", "11002", "11003", "11010", "11013", "11015" ], "enumTitles": [ "All tags (unfiltered + 5 tags)", "Beauty & Care", "Fashion", "Food & Beverage", "Lifestyle & Leisure", "Technology & Finance" ] }, "default": [], "prefill": [] }, "weeksBack": { "title": "Extra Weekly Windows", "type": "integer", "description": "(mode=trendingVideos) Add past weekly rankings by moving the chart end date back 7 days per step (0-4). Useful for comparing this week with earlier weeks.", "default": 0, "minimum": 0, "maximum": 4, "prefill": 0 }, "includeTopComments": { "title": "Include Top Comments", "type": "boolean", "description": "(mode=trendingVideos) Add each video's top comments and comment keywords. Each video's comments are read separately (up to 100 videos per run).", "default": false, "prefill": false }, "maxItems": { "title": "Maximum Rows", "type": "integer", "description": "Maximum number of data rows to write per run. Creator rows are not counted.", "default": 1000, "minimum": 1, "maximum": 5000, "prefill": 10 } }, "required": [] }, "output": { "actorOutputSchemaVersion": 1, "title": "TikTok Hashtag Momentum & Top Creator Tracker Output", "description": "Trending-hashtag rows with ranks, post and view counts, popularity curves, momentum signals and top creators; optional creator-leader rows; trending-video rows with engagement metrics and author stats.", "properties": { "data": { "type": "string", "title": "Trending Hashtags and Videos", "description": "Dataset containing hashtag rows, optional creator-leader rows, and trending-video rows.", "template": "{{links.apiDefaultDatasetUrl}}/items" } } }, "dockerfile": "./Dockerfile", "storages": { "dataset": { "actorSpecification": 1, "title": "TikTok Hashtag Trends and Videos", "views": { "overview": { "title": "Hashtags Overview", "description": "One row per hashtag, market and window, plus optional creator-leader and trending-video rows in the same dataset (see the rowType field).", "transformation": { "fields": [ "rowType", "rankIndex", "hashtagName", "publishCnt", "vv", "observedCountry", "observedPeriod", "scrapedAt" ] }, "display": { "component": "table", "properties": { "rowType": { "label": "Row Type", "format": "text" }, "rankIndex": { "label": "Rank", "format": "number" }, "hashtagName": { "label": "Hashtag", "format": "text" }, "publishCnt": { "label": "Post Count", "format": "number" }, "vv": { "label": "Video Views", "format": "number" }, "observedCountry": { "label": "Country", "format": "text" }, "observedPeriod": { "label": "Period (Days)", "format": "number" }, "scrapedAt": { "label": "Scraped At", "format": "text" } } } }, "videos": { "title": "Trending Videos", "description": "Video rows from the trending-video chart, with author context and engagement metrics.", "transformation": { "fields": [ "rowType", "caption", "views", "engagementRate", "author.username", "observedCountry", "createdAt" ] }, "display": { "component": "table", "properties": { "rowType": { "label": "Row Type", "format": "text" }, "caption": { "label": "Caption", "format": "text" }, "views": { "label": "Views", "format": "number" }, "engagementRate": { "label": "Engagement Rate", "format": "number" }, "author.username": { "label": "Author", "format": "text" }, "observedCountry": { "label": "Country", "format": "text" }, "createdAt": { "label": "Created", "format": "text" } } } } }, "fields": { "rowType": { "type": "string", "title": "Row Type", "description": "Discriminator: 'hashtag' for ranked hashtag rows, 'creator' for the optional creator leaderboard, 'video' for trending-video rows." }, "hashtagId": { "type": "string", "title": "Hashtag ID", "description": "TikTok's internal hashtag ID (string to preserve 64-bit precision)." }, "hashtagName": { "type": "string", "title": "Hashtag", "description": "Hashtag text without the leading #." }, "hashtagUrl": { "type": "string", "title": "Hashtag URL", "description": "Durable TikTok tag page URL." }, "rankIndex": { "type": "integer", "title": "Rank", "description": "1-based position in the overall chart when available, otherwise the best industry-chart position. See isOverallRanking and rankingSlices." }, "publishCnt": { "type": "integer", "title": "Post Count", "description": "Number of posts published with this hashtag during the observed window." }, "vv": { "type": "integer", "title": "Video Views", "description": "Total video views accumulated by posts using this hashtag during the observed window." }, "avgViewsPerPost": { "type": "integer", "title": "Average Views per Post", "description": "vv divided by publishCnt, rounded." }, "popularityCurve": { "type": "array", "title": "Popularity Curve", "description": "Day-by-day TikTok popularity index (0-100) for the observed window: [{date, value}].", "items": { "type": "object" } }, "momentumChangePct": { "type": "number", "title": "Momentum Change (%)", "description": "Change between the mean of the most recent third of the popularity curve and the third before it, as a percentage of TikTok's normalized index." }, "trendDirection": { "type": "string", "title": "Trend Direction", "description": "rising, steady or falling, derived from momentumChangePct with a +/-10% threshold." }, "trendStage": { "type": "string", "title": "Trend Stage", "description": "breaking, peaking, fading or steady, derived from the curve peak position and recent change." }, "peakDate": { "type": "string", "title": "Peak Date", "description": "Date of the highest popularity value in the window." }, "peakValue": { "type": "number", "title": "Peak Value", "description": "Highest popularity value in the window (TikTok's 0-100 index)." }, "curveVolatility": { "type": "number", "title": "Curve Volatility", "description": "Population standard deviation of the popularity curve values." }, "industryIds": { "type": "array", "title": "Industry IDs", "description": "TikTok industry category IDs assigned to this hashtag.", "items": { "type": "string" } }, "industryNames": { "type": "array", "title": "Industries", "description": "Human-readable names for the assigned industry categories.", "items": { "type": "string" } }, "isOverallRanking": { "type": "boolean", "title": "Overall Chart", "description": "True when the hashtag appeared on the market's overall chart rather than only an industry chart." }, "rankingSlices": { "type": "array", "title": "Industry Charts", "description": "Industry chart IDs in which the hashtag also ranked (present when it ranked in at least one industry slice).", "items": { "type": "string" } }, "topCreators": { "type": "array", "title": "Top Creators", "description": "Creators TikTok credits for this hashtag: rank, ttuid, handleName, nickname, followerCount, countryCode and avatarUrl (signed CDN link).", "items": { "type": "object" } }, "creatorId": { "type": "string", "title": "Creator ID", "description": "TikTok user ID for creator-leader rows." }, "handleName": { "type": "string", "title": "Handle", "description": "Creator username without @ (creator rows)." }, "nickname": { "type": "string", "title": "Display Name", "description": "Creator display name (creator rows)." }, "followerCount": { "type": "integer", "title": "Followers", "description": "Highest follower count observed for the creator in the collected rows." }, "countryCode": { "type": "string", "title": "Country", "description": "Creator country code as reported by TikTok." }, "avatarUrl": { "type": "string", "title": "Avatar URL", "description": "Signed TikTok CDN avatar link (temporary)." }, "appearances": { "type": "integer", "title": "Trend Appearances", "description": "Number of collected hashtag rows in which TikTok credited this creator." }, "hashtags": { "type": "array", "title": "Hashtags", "description": "Hashtag names the creator was credited on (creator rows) or hashtags parsed from a video caption (video rows).", "items": { "type": "string" } }, "bestRank": { "type": "integer", "title": "Best Rank", "description": "Creator's best top-creator rank across the collected hashtags." }, "observedCountries": { "type": "array", "title": "Markets", "description": "Markets in which the creator appeared (creator rows).", "items": { "type": "string" } }, "observedPeriods": { "type": "array", "title": "Windows", "description": "Time windows in days in which the creator appeared (creator rows).", "items": { "type": "integer" } }, "videoId": { "type": "string", "title": "Video ID", "description": "TikTok video ID (video rows)." }, "videoUrl": { "type": "string", "title": "Video URL", "description": "Durable TikTok video page URL (video rows)." }, "embedUrl": { "type": "string", "title": "Embed URL", "description": "Durable cookieless TikTok embed player URL (video rows)." }, "caption": { "type": "string", "title": "Caption", "description": "Video caption text (video rows)." }, "createTime": { "type": "integer", "title": "Create Time (Unix)", "description": "Video publish time as a Unix timestamp." }, "createdAt": { "type": "string", "title": "Created At", "description": "Video publish time in ISO 8601 UTC." }, "ageDays": { "type": "number", "title": "Age (Days)", "description": "Age of the video at collection time, in days." }, "coverUrl": { "type": "string", "title": "Cover URL", "description": "Signed TikTok CDN cover link (temporary, about 48 hours)." }, "author": { "type": "object", "title": "Author", "description": "Video author object: id, username, displayName, bio, followerCount and avatarUrl." }, "views": { "type": "integer", "title": "Views", "description": "Video views within the observed window." }, "organicViews": { "type": "integer", "title": "Organic Views", "description": "Organic (non-promoted) views within the observed window." }, "engagementRate": { "type": "number", "title": "Engagement Rate", "description": "TikTok's engagement rate for the video in the observed window." }, "sixSecondViewRate": { "type": "number", "title": "6-Second View Rate", "description": "Share of viewers who watched at least six seconds." }, "viewsLifeTime": { "type": "integer", "title": "Lifetime Views", "description": "Lifetime video views reported by TikTok." }, "organicViewsLifeTime": { "type": "integer", "title": "Lifetime Organic Views", "description": "Lifetime organic video views reported by TikTok." }, "engagementRateLifeTime": { "type": "number", "title": "Lifetime Engagement Rate", "description": "Lifetime engagement rate reported by TikTok." }, "sixSecondViewRateLifeTime": { "type": "number", "title": "Lifetime 6-Second View Rate", "description": "Lifetime share of viewers who watched at least six seconds." }, "viewsPerDay": { "type": "integer", "title": "Views per Day", "description": "Window views divided by the video's age in days." }, "lifetimeViewsShare": { "type": "number", "title": "Window Share of Lifetime Views", "description": "Window views divided by lifetime views." }, "topComments": { "type": "array", "title": "Top Comments", "description": "Up to 50 most-liked comments on the video (when Include top comments is on).", "items": { "type": "object" } }, "commentKeywords": { "type": "array", "title": "Comment Keywords", "description": "Keywords TikTok extracted from the video's comments and their mention counts.", "items": { "type": "object" } }, "observedCountry": { "type": "string", "title": "Observed Country", "description": "ISO country code of the market whose chart produced this row." }, "observedPeriod": { "type": "integer", "title": "Observed Period (Days)", "description": "Lookback window in days used for this row: 7, 30 or 90 for hashtags; 7 or 30 for videos." }, "videoSortBy": { "type": "string", "title": "Video Ranking Metric", "description": "Metric used for the video chart: views, engagementRate or sixSecondViewRate." }, "weeksBack": { "type": "integer", "title": "Weeks Back", "description": "How many weekly steps back the chart end date was moved for this row (0 = latest)." }, "scrapedAt": { "type": "string", "title": "Scraped At", "description": "ISO 8601 UTC datetime when this row was collected." }, "dataSource": { "type": "string", "title": "Data Source", "description": "Always 'tiktok-creative-center'." }, "contentTag": { "type": "string", "title": "Content Tag", "description": "Content-tag ranking that surfaced this video (11002 Beauty & Care, 11003 Fashion, 11010 Food & Beverage, 11013 Lifestyle & Leisure, 11015 Technology & Finance). Omitted for the unfiltered ranking." }, "rankingKey": { "type": "string", "title": "Ranking Key", "description": "Provenance of the ranking that produced this row: market:window:sort:weeksBack:tag (tag 'all' = unfiltered)." } } } } }, "buildNumber": "1.0.2", "imageDigest": "4351990c3e727b294cabb0486a4512f3b023a43cddacabfeebd0f068fe8393de", "actVersion": { "sourceType": "SOURCE_FILES", "buildTag": "latest", "versionNumber": "1.0" }, "usage": { "ACTOR_COMPUTE_UNITS": 0.045893333333333335 } } }