TikTok Trend Scout — Viral Hashtag & Video Trend API for AI Agents

TikTok trend intelligence for AI agents and content-strategy pipelines — trending hashtags and videos with real view counts, post counts, and daily momentum curves, returned as typed JSON rows (schema below).

Trend Scout pulls TikTok's own Creative Center trend indexes: ranked trending hashtags per country and period with views, posts, industry categories, top creators, and a day-by-day popularity curve that shows whether a trend is accelerating or fading; plus the top trending videos with view counts, engagement rate, and 6-second view-through. Cross-country hashtag lookup and a legacy URL-fetch mode round it out. No login, no cookies, no API keys.

Why agents use this actor

• Real trend numbers, straight from TikTok's trend index — view counts, post counts, ranks, and a 0–100 daily momentum curve per hashtag. momentumScore: 100 means the hashtag peaked today.
• Deterministic typed output — every row carries trendType, and every field is documented in a published dataset schema. No surprise shapes.
• Cost-predictable — maxItems caps rows per run; one run, one bounded dataset. Safe for autonomous budgets.
• No auth, cookies, or API keys — works out of the box.
• Clear error semantics — per-source failures land in the SUMMARY key-value record; zero-result runs exit non-zero. Never a silent empty success.
• Rate-limit handling built in — automatic retry with backoff on HTTP 429/5xx, browser-grade TLS fingerprinting, 30-second timeout per request.

Modes

Mode	What it returns
trending-hashtags (default)	Ranked trending hashtags for a country and period (7/30/120 days) with views, posts, momentum curve, industries, and top creators. Scan multiple countries in one run via countryCodes.
trending-videos	Top trending videos for a country (up to 100), ranked by views, engagement, or 6-second views — with watch URL, author, and full metrics.
hashtag-stats	Looks up specific hashtags across TikTok's trending indexes (all 27 countries × all periods by default) and returns their stats; found: false rows for hashtags not currently trending anywhere.
url-fetch	Legacy mode: fetches arbitrary URLs and returns url/statusCode/ok/title/error rows. Runs automatically when URLs are supplied without a mode.

Input schema

Field	Type	Required	Default	Description
mode	string	no	trending-hashtags (URLs present → url-fetch)	One of trending-hashtags, trending-videos, hashtag-stats, url-fetch.
countryCode	string	no	US	Country for the trend index. Hashtags: 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. Videos: US, JP, VN, TH, ID.
countryCodes	array of strings	no	—	Multiple countries in one run (trending-hashtags, hashtag-stats). Overrides countryCode.
period	integer	no	7	Trending window in days: 7, 30, or 120 (hashtag modes).
hashtags	array of strings	for hashtag-stats	—	Hashtag names to look up, with or without the leading #.
orderBy	string	no	views	Video ranking metric: views, engagement, or sixSecondsViews.
maxItems	integer	no	100	Maximum dataset rows per run in trend modes.
urls / url / startUrls	array / string / array	no	—	Legacy url-fetch inputs (unchanged from previous versions).
maxRequestsPerCrawl	integer	no	20	Legacy mode: max unique URLs per run.

Output schema

Hashtag rows (trending-hashtags, hashtag-stats):

Field	Type	Nullable	Description
trendType	string	no	"hashtag"
rank	integer	yes	Position in the trending index (1 = top).
hashtagName	string	no	Hashtag without the #.
hashtagId	string	yes	TikTok internal hashtag ID.
viewCount	number	yes	Views of posts under the hashtag in the period.
publishCount	number	yes	Posts published under the hashtag in the period.
videoCount	number	yes	Videos under the hashtag in the period (equals publishCount).
countryCode	string	yes	Country of the index the row came from.
period	integer	yes	Window in days (7/30/120).
industryIds	array	no	TikTok industry category IDs.
popularityCurve	array	no	Daily { timestamp, value } momentum signal, value 0–100.
momentumScore	number	yes	Latest curve value; 100 = peaking right now.
topCreators	array	no	Creators driving the tag: { handleName, nickname, followerCount, countryCode }.
found	boolean	—	hashtag-stats only: whether the hashtag is currently in any trending index.

Video rows (trending-videos): trendType: "video", rank, title, videoId, videoUrl, coverUrl, createTime (ISO 8601), viewCount, viewCountLifetime, engagementRate, sixSecondsViewRate, authorHandle, authorName, authorFollowers, contentTags, countryCode, period.

Legacy url-fetch rows: url, statusCode, ok, title, error — identical to previous versions.

Example hashtag row:

{
  "trendType": "hashtag",
  "rank": 1,
  "hashtagName": "this_and_that",
  "hashtagId": "1603180434501637",
  "viewCount": 29131906,
  "publishCount": 15590,
  "videoCount": 15590,
  "countryCode": "US",
  "period": 7,
  "industryIds": ["23000000000"],
  "popularityCurve": [{ "timestamp": 1786060800, "value": 45.83 }, { "timestamp": 1786579200, "value": 100 }],
  "momentumScore": 100,
  "topCreators": [{ "handleName": "jordan_the_stallion8", "nickname": "Jordan_The_Stallion8", "followerCount": 19647889, "countryCode": "US" }]
}

Example video row:

{
  "trendType": "video",
  "rank": 1,
  "title": "Designed to match your vibe...",
  "videoId": "7665338027799104781",
  "videoUrl": "https://www.tiktok.com/@thepacman82/video/7665338027799104781",
  "createTime": "2026-07-22T04:26:47.000Z",
  "viewCount": 82604098,
  "viewCountLifetime": 82795783,
  "engagementRate": 0.00315,
  "sixSecondsViewRate": 0.2417,
  "authorHandle": "thepacman82",
  "authorName": "Phil Cohen",
  "authorFollowers": 323515,
  "contentTags": ["Technology & Finance"],
  "countryCode": "US",
  "period": 7
}

A SUMMARY record is written to the run's key-value store: { "mode", "pushed", "failed", "failures": [...] } (legacy mode adds requestedUrls and fetched).

Error semantics

• Missing required input (e.g. hashtag-stats without hashtags, url-fetch without URLs) → fails fast, exit code 1, explanatory status message. Nothing billed.
• Per-source failure → recorded in SUMMARY.failures with the source and error; remaining sources still processed.
• Zero successful rows → exit code 1 with a status message pointing at SUMMARY. Agents: treat exit 1 as retryable-after-fixing-input.
• HTTP 429/5xx → retried up to 3 times with backoff before counting as a failure.

Use from AI agents (MCP)

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/?tools=apricot_blackberry/tiktok-trend-scout",
      "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" }
    }
  }
}

Works in Claude, Cursor, ChatGPT deep research connectors, and any MCP client; the input schema above is the tool's parameter schema.

Use from code

curl:

curl -X POST "https://api.apify.com/v2/acts/apricot_blackberry~tiktok-trend-scout/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "trending-hashtags", "countryCode": "US", "period": 7}'

JavaScript (apify-client):

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('apricot_blackberry/tiktok-trend-scout').call({
    mode: 'trending-hashtags', countryCode: 'US', period: 7,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python (apify_client):

from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("apricot_blackberry/tiktok-trend-scout").call(run_input={
    "mode": "trending-hashtags", "countryCode": "US", "period": 7,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)

Use from automation platforms

• n8n / Make / Zapier: use the native Apify integration and choose the actor by name (apricot_blackberry/tiktok-trend-scout).
• LangChain / LlamaIndex: use the Apify actor tool wrappers with the same actor id and input shape.
• Webhooks: Apify can fire a webhook on ACTOR.RUN.SUCCEEDED/FAILED for this actor, so a scheduled trend scan can push straight into a content-planning pipeline without polling.

Pricing

Pay per event: $0.05 actor start + $0.01 per result row (hashtag, video, or lookup). maxItems and maxRequestsPerCrawl cap rows per run, so cost scales linearly and predictably.

Use cases

• Trend surfing: run trending-hashtags on a schedule; filter for momentumScore > 80 to catch hashtags while they're still climbing.
• Content planning: pull trending-videos ranked by 6-second views to study what hooks are working this week.
• Campaign monitoring: hashtag-stats on your campaign tags to see when and where they break into a national trending index.
• Market comparison: pass countryCodes: ["US", "GB", "DE", "JP"] and compare which trends travel across markets.

Works great with

• TikTok Profile Scraper — deep-scrape the creators behind the trends you track.

FAQ

Does it log in to TikTok? No. It reads TikTok's public Creative Center trend indexes — no auth, cookies, or session state.

How many hashtags per country? TikTok's public index exposes its top trending hashtags per country and period; scan multiple countries and periods in one run to widen coverage.

What does momentumScore mean? It's the latest point of TikTok's own 0–100 daily popularity curve for the hashtag. 100 means the tag peaked on the most recent day — a rising-trend signal; near 0 means it already faded.

What about trending sounds? Sound-level trend data currently requires a TikTok Business login and is not included; hashtag and video trend data cover the public indexes.

Are old url-fetch integrations still supported? Yes — supplying urls/url/startUrls without a mode runs the original url-fetch behavior with the identical output contract.

Changelog

• 2026-08-15 — Rebuilt extraction engine on TikTok's Creative Center trend indexes: new trending-hashtags, trending-videos, and hashtag-stats modes with real view counts, post counts, ranks, momentum curves, top creators, and full video metrics. Multi-country scanning, browser-grade TLS fingerprinting, expanded dataset schema. Legacy url-fetch mode preserved unchanged.
• 2026-08-14 — Published dataset output schema; agent-first README and MCP integration docs; fail-loud behavior on empty input and total fetch failure; retry with backoff on HTTP 429/5xx; 30 s per-request timeout; SUMMARY key-value record.

---

Built by Creator Fusion — OSINT tools that actually work.