# TikTok Trending Hashtags And Videos Scraper (`scrapeengine/tiktok-trending-hashtags-scraper`) Actor

🔥 TikTok Trending Hashtags And Videos Scraper pulls real-time trending tags, views, and engagement. 🔍 Hashtag research: related tags, popularity, growth. 📈 Export CSV/JSON or use API. 🚀 Ideal for creators, brands, and marketers.

- **URL**: https://apify.com/scrapeengine/tiktok-trending-hashtags-scraper.md
- **Developed by:** [ScrapeEngine](https://apify.com/scrapeengine) (community)
- **Categories:** Automation, Lead generation, Social media
- **Stats:** 7 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$19.99/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period.You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#rental-actors

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### TikTok Trending Hashtags Scraper — Rank, Views and Top Videos

TikTok Trending Hashtags And Videos Scraper pulls the live trending-hashtag ranking for any country, time window, and industry, then opens each hashtag's own TikTok page to capture its real top videos — caption, author, music, and engagement stats — as linked child rows. Every `hashtag_name`, `rank`, `video_views`, `trend`, and `diggCount` returns as structured JSON, no HTML parsing needed. Start a run below to pull your first ranking.

### What is TikTok Trending Hashtags And Videos Scraper?

It's an Apify Actor that discovers TikTok's currently trending hashtags — ranked by country, 7/30/120-day window, and industry category — and, for each one, fetches the hashtag's real live top videos as linked child rows carrying a `parentId` back to the parent hashtag. It returns one structured JSON dataset with no manual parsing. No TikTok account or login is required or used anywhere in the run. It's built for social media marketers, agencies, creators, and researchers who need both the trend signal and the content behind it in one place.

### What TikTok trending data is publicly available to scrape?

TikTok's Creative Center exposes a small anonymous preview of the hashtag ranking with no login; the full 100-hashtag list needs a logged-in TikTok Ads account.

| Data Category | Public (no login) | Restricted (logged-in Ads account) |
| --- | --- | --- |
| Hashtag name, rank, view/publish counts | Small preview, per country/period | Full ranked list |
| Popularity curve (trend history) | Yes, for previewed hashtags | — |
| Country/industry tagging | Yes | Industry & "new entrant" server-side filtering |
| Rank-change direction | Not exposed today | — |
| Top videos per hashtag | Yes, via the public hashtag page | — |
| Ad/promoted flag | Not exposed today | — |

This Actor only returns publicly visible data — what any visitor sees, nothing behind a login wall.

### What data can I extract with TikTok Trending Hashtags And Videos Scraper?

Each run returns two linked row types — hashtag rows (`type: "hashtag"`) and video rows (`type: "video"`, linked via `parentId`) — covering ranking, engagement, and per-video creator data.

#### Hashtag identity, ranking and country/industry fields

| Field Name | Description |
| --- | --- |
| `id` / `hashtag_id` | The hashtag's TikTok ID |
| `hashtag_name` | The hashtag text, without `#` |
| `type` | `"hashtag"` for parent rows, `"video"` for linked video rows |
| `isChild` / `parentId` | `false`/`null` for hashtag rows; `true` and the parent hashtag ID for video rows |
| `rank` | Position in the trending ranking |
| `rank_diff_type` / `rank_change_readable` | Raw rank-change code and a human label ("Up"/"Down"/"Same"/"New"); both `null` when TikTok's live endpoint doesn't expose the field |
| `period` | The requested ranking window in days |
| `country_info` | Object (`code`, `name`) — the row's true source country |
| `industry_info` | Object (`industry_ids`, `industry_labels`), or `null` if untagged |
| `is_promoted` | Boolean ad flag, `null` when TikTok doesn't expose it for that row |
| `webVideoUrl` | Public hashtag page link (hashtag rows) or the video's own deep link (video rows) |

#### Hashtag metrics and trend fields

| Field Name | Description |
| --- | --- |
| `video_views` | Total views reported for the hashtag |
| `publish_cnt` | Total videos published under the hashtag |
| `trend` | Array of `{ "time", "value" }` popularity-curve points |
| `analytics` | Extra blob (`video_views`, `publish_cnt`, `rank`, `industry_ids`, `trend`, `creators`) — present only when Result Mode includes analytics |

#### Linked video, creator and AI fields

| Field Name | Description |
| --- | --- |
| `caption` | The video's on-screen caption/description text |
| `authorMeta` | Object: `id`, `uniqueId`, `nickname`, `verified`, `avatar`, `followers`, `following`, `heart`, `videoCount` |
| `musicMeta` | Object: `musicId`, `musicName`, `musicAuthor`, `original`, `playUrl` |
| `videoMeta` | Object: `duration`, `width`, `height`, `coverUrl` |
| `diggCount` / `playCount` / `commentCount` / `shareCount` / `collectCount` | Likes, plays, comments, shares, saves |
| `hashtags` | Other hashtags detected in the caption/challenges |
| `createTime` / `createTimeISO` | Video publish time, raw and ISO-8601 |
| `aiSentiment` / `aiTopics` / `aiLanguage` | Caption sentiment, topic keywords, detected language — filled only when AI caption analysis is on and a valid key is supplied, otherwise `null` |
| `scrapedAt` | ISO-8601 UTC timestamp of collection |

##### 🤖 Add-on: Need additional TikTok data?

Pair this Actor with [Trending Videos Insights and Branded Hashtag Views & Likes](../tiktok-trending-videos-insights-and-branded-hashtag-views-likes) for TikTok Top Ads cost/CTR analytics (brand, cost-per-like, engagement score) rather than organic hashtag trends. If you need creator profiles attached to individual trending videos without going through a hashtag, [TikTok Trending Videos Scraper With Author Profile](../tiktok-trending-videos-scraper-with-author-profile) fetches discovery-mode or direct-URL videos with full author bio and follower data.

### How does TikTok Trending Hashtags And Videos Scraper differ from the official TikTok API?

TikTok's own public developer program is the Research API, and it is not a general commercial access point: eligibility is limited to vetted academic institutions and not-for-profit/independent research bodies (in the US, EEA, UK, Switzerland, or youth-safety researchers in Brazil), applicants must submit a justified research proposal and proof of ethics approval, and TikTok's own overview states approval typically takes about four weeks (TikTok Developers, "Research API & Display API," checked 2026-07-25).

| Feature | TikTok Research API | TikTok Trending Hashtags And Videos Scraper |
| --- | --- | --- |
| Who can access it | Approved academic/non-profit researchers only | Anyone with an Apify account |
| Approval process | Application + ethics review, ~4-week typical wait | None — runs immediately |
| Trending hashtag ranking by country/industry | Not a documented product feature | Yes, built in |
| Per-hashtag top videos as linked rows | Not documented | Yes, via `parentId` |
| Commercial use of the data | Prohibited (non-commercial research only) | Unrestricted |
| Output format | Research-specific export under TikTok's terms | Structured JSON dataset |

Use TikTok's Research API only if you already qualify as an approved academic or non-profit researcher and need it under TikTok's own terms. Use this Actor when you need trending-hashtag and video data now, for commercial or operational use, without an application process.

### How to use TikTok Trending Hashtags And Videos Scraper

No input field is required — the default configuration runs a global trending-hashtag ranking out of the box. To scope a run:

1. Open TikTok Trending Hashtags And Videos Scraper on Apify and click **Start**.
2. Pick `resultMode` — 🏆 Trending Ranking, 📊 Ranking + Analytics, or 🔬 Custom Hashtag Analytics for your own `hashtagsToAnalyze` list.
3. Set `targetCountry`, `trendingWindow`/`analyticsWindow`, `industryCategory`, and `maxHashtags` (up to 100) to scope the ranking; toggle `fetchTopVideos` and `maxVideosPerHashtag` (up to 50) for linked video rows.
4. Start the run and let it finish.
5. Download the dataset as JSON, CSV, or Excel, or read it via the Apify API.

#### How to scale to bulk TikTok trending extraction

There's no URL list — scale comes from the parameters themselves. `maxHashtags` collects up to 100 hashtag rows per run, each with up to 50 linked videos via `maxVideosPerHashtag`. For custom analytics, `hashtagsToAnalyze` accepts an unlimited array of your own hashtags in one run. To cover every market, either set `targetCountry` to 🌐 All (which aggregates real per-country batches automatically) or loop separate runs across specific country codes.

### What can you do with TikTok trending hashtag data?

- A social media manager tracking trend timing uses `rank`, `rank_change_readable`, and `trend` to catch a hashtag's popularity curve before it peaks.
- A marketing strategist prioritizing campaign hashtags uses `hashtag_name`, `video_views`, and `publish_cnt` to pick hashtags with real, current reach.
- A creator or agency doing content research uses each hashtag's linked `caption`, `authorMeta`, and `diggCount`/`playCount` to see which creators and formats are winning under a trend right now.
- A competitive-intel or brand-safety analyst uses `industry_info` and `country_info` to benchmark which topics are trending by market and vertical.
- An AI/LLM use case: an agent building an automated trend briefing feeds `hashtag_name`, `caption`, `aiSentiment`, and `aiTopics` straight into an LLM to summarize what's driving a trend this week, with no HTML scraping or selector maintenance.

### How does TikTok Trending Hashtags And Videos Scraper handle rate limits and blocking?

The Actor navigates a real TikTok Creative Center page first, through a headless Chromium browser (Playwright), to seed an anonymous session before requesting hashtag data — reducing bot suspicion rather than hitting the API cold. Hashtag requests retry up to 3 times with exponential backoff on a non-200 response or network error. TikTok's tag pages occasionally return an empty response body for the video-list request — a soft anti-bot response, not a hard block — so the video fetch retries once on a fresh browser context/session before giving up on that hashtag; no video rows are fabricated if both attempts come back empty. An optional `proxyConfiguration` (off by default) can route both the hashtag and video requests through Apify proxy. If a hashtag's video fetch errors outright, that hashtag's row is still pushed and the run continues with the remaining hashtags.

### ⬇️ Input

| Parameter | Required | Type | Description | Example Value |
| --- | --- | --- | --- | --- |
| `resultMode` | No | string (enum) | 🏆 Trending Ranking / 📊 Ranking + Analytics / 🔬 Custom Hashtag Analytics for your own hashtag list | `"top100"` |
| `targetCountry` | No | string (enum) | Country to pull trends for, or 🌐 All Countries for global aggregation | `"US"` |
| `trendingWindow` | No | string (enum) | Time window for the trending ranking: `"7"`, `"30"`, or `"120"` days | `"7"` |
| `analyticsWindow` | No | string (enum) | Time window for analytics curves: `"7"`, `"30"`, `"120"`, `"365"`, or `"1095"` days | `"30"` |
| `industryCategory` | No | string (enum) | Narrow the ranking by industry; leave blank for all industries | `"20000000001"` |
| `onlyNewEntries` | No | boolean | Return only hashtags newly entering the ranking (default `false`) | `false` |
| `maxHashtags` | No | integer | Cap on hashtag rows to collect, 1–100 | `20` |
| `hashtagsToAnalyze` | No | array | Your own hashtags (no `#`) to analyze — used only in 🔬 Custom Hashtag Analytics mode | `["skincare", "fyp"]` |
| `fetchTopVideos` | No | boolean | Fetch each hashtag's top videos as linked child rows (default `true`) | `true` |
| `maxVideosPerHashtag` | No | integer | Cap on video rows per hashtag, 0–50 (default `5`) | `5` |
| `enableAiAnalysis` | No | boolean | Turn on AI sentiment/topic/language classification of video captions (default `false`) | `false` |
| `aiModel` | No | string (enum) | AI model/provider for caption classification (default `"claude-haiku-4-5"`) | `"claude-haiku-4-5"` |
| `aiApiKey` | No | string (secret) | Your own API key for the selected AI provider; required only when AI analysis is on | `"sk-ant-..."` |
| `proxyConfiguration` | No | object | Apify proxy configuration; no proxy used by default | `{ "useApifyProxy": false }` |

#### Example input

```json
{
  "resultMode": "top100_with_analytics",
  "targetCountry": "US",
  "trendingWindow": "7",
  "analyticsWindow": "30",
  "industryCategory": "",
  "onlyNewEntries": false,
  "maxHashtags": 20,
  "hashtagsToAnalyze": [],
  "fetchTopVideos": true,
  "maxVideosPerHashtag": 5,
  "enableAiAnalysis": false,
  "aiModel": "claude-haiku-4-5",
  "aiApiKey": "",
  "proxyConfiguration": { "useApifyProxy": false }
}
```

### ⬆️ Output

Each run writes typed, normalized JSON rows to one Apify dataset, exportable as JSON, CSV, Excel, or XML — field names stay the same across runs. Video rows are also mirrored to a separate per-run video dataset. Every pushed row, hashtag or video, bills one `row_result` charged event; no separate uncharged accounting rows are pushed.

#### Example output

Hashtag (parent) row:

```json
{
  "id": "163892104123456789",
  "type": "hashtag",
  "isChild": false,
  "parentId": null,
  "hashtag_id": "163892104123456789",
  "hashtag_name": "skincare",
  "caption": null,
  "country_info": { "code": "US", "name": "United States", "id": "US", "value": "United States", "label": "US" },
  "industry_info": { "industry_ids": ["20000000001"], "industry_labels": ["Beauty & Personal Care"] },
  "is_promoted": null,
  "trend": [ { "time": 1752537600, "value": 812345 }, { "time": 1752624000, "value": 843210 } ],
  "video_views": 98234123,
  "publish_cnt": 45211,
  "rank": 3,
  "rank_diff_type": null,
  "rank_change_readable": null,
  "period": "7",
  "authorMeta": null,
  "musicMeta": null,
  "diggCount": null,
  "playCount": null,
  "commentCount": null,
  "shareCount": null,
  "webVideoUrl": "https://www.tiktok.com/tag/skincare",
  "aiSentiment": null,
  "aiTopics": null,
  "aiLanguage": null,
  "scrapedAt": "2026-07-25T10:14:32.501Z"
}
```

Linked video (child) row:

```json
{
  "id": "7398214410023456789",
  "type": "video",
  "isChild": true,
  "parentId": "163892104123456789",
  "hashtag_name": "skincare",
  "caption": "morning routine that actually cleared my skin #skincare",
  "is_promoted": false,
  "createTime": 1753180800,
  "createTimeISO": "2026-07-22T08:00:00+00:00",
  "authorMeta": { "uniqueId": "glow.with.k", "nickname": "Glow with K", "verified": false, "followers": 184200, "following": 312, "heart": 5210044, "videoCount": 812 },
  "musicMeta": { "musicId": "70123456789", "musicName": "original sound", "musicAuthor": "glow.with.k", "original": true },
  "videoMeta": { "duration": 38, "width": 1080, "height": 1920, "coverUrl": "https://p16-sign.tiktokcdn.com/example-cover.jpeg" },
  "diggCount": 48213,
  "playCount": 1204531,
  "commentCount": 621,
  "shareCount": 1890,
  "collectCount": 3021,
  "hashtags": ["skincare", "skincareroutine", "fyp"],
  "webVideoUrl": "https://www.tiktok.com/@glow.with.k/video/7398214410023456789",
  "aiSentiment": "positive",
  "aiTopics": ["skincare", "morning-routine", "beauty"],
  "aiLanguage": "en",
  "scrapedAt": "2026-07-25T10:14:41.223Z"
}
```

### How does it work?

The Actor launches a headless Chromium browser and first opens TikTok's own Creative Center trends page to seed a real anonymous session and cookies. It then posts to TikTok's live hashtag-ranking endpoint — the same request the page's own JavaScript fires — to collect the trending hashtag list for the chosen country, window, and industry. When video fetching is on, it opens each hashtag's public `tiktok.com/tag/` page in a fresh browser context and listens for the same video-list network response the real page loads, capturing caption, author, music, and stats directly from TikTok's own traffic rather than parsed HTML. Only data any visitor can already see is returned — nothing requires a TikTok login. Field names stay stable across runs even as TikTok changes its page layout, because the Actor reads structured API responses, not the visual page.

### Integrations

TikTok Trending Hashtags And Videos Scraper runs on Apify, so it works with anything that can call an HTTP API or the Apify client libraries — no proprietary SDK required.

#### Calling TikTok Trending Hashtags And Videos Scraper programmatically

```python
from apify_client import ApifyClient

client = ApifyClient("<APIFY_API_TOKEN>")

run = client.actor("scraper-engine/tiktok-trending-hashtags-and-videos-scraper").call(run_input={
    "targetCountry": "US",
    "maxHashtags": 20,
    "fetchTopVideos": True,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["hashtag_name"], item.get("rank"))
```

Works in Go, Ruby, Node.js, cURL — any language that can make an HTTP request.

#### MCP integration for AI agents

TikTok Trending Hashtags And Videos Scraper is reachable through Apify's Actors MCP Server at `https://mcp.apify.com`, which exposes Apify Store Actors as callable tools for MCP-compatible clients including Claude Desktop, Claude Code, Cursor, and VS Code. Connect it with `apify mcp install claude-code --tools scraper-engine/tiktok-trending-hashtags-and-videos-scraper`, or add the hosted URL with a bearer-token `Authorization` header to any MCP client config.

#### No-code tools (n8n, Make, LangChain)

In n8n, use the HTTP Request node (or the community Apify node) pointed at this Actor's run endpoint, with your Apify API token in the Authorization header. In Make, use the Apify app's "Run Actor and get dataset items" module to feed hashtag/video rows into a downstream scenario. In LangChain, call the same Apify API endpoint from a custom Tool, or load the dataset with the community Apify loader, so an agent can pull current TikTok trends mid-conversation.

### Is it legal to scrape TikTok trending content?

Scraping publicly available TikTok data is generally lawful, since this Actor only returns what any visitor can already see on TikTok's public trends page and public hashtag video feeds — no login wall, no private account data. The hashtag ranking and analytics fields (views, publish counts, trend curves) are aggregate content metrics, not personal data. The linked video rows do include public creator handles, nicknames, and follower counts, which can qualify as personal data about an identifiable individual, so storing or reusing that data at scale can fall under GDPR/CCPA-type regimes, and TikTok's own Terms of Service separately restrict automated access. Consult legal counsel if your use case involves bulk storage or reuse of creator data, especially across the EU/UK or California.

### Frequently asked questions

#### What TikTok hashtag and video fields does this scraper return?

It returns `hashtag_name`, `rank`, `video_views`, `publish_cnt`, and `trend` for every hashtag, plus `caption`, `authorMeta`, `diggCount`, and `webVideoUrl` for every linked video. See the full data fields tables above for every key.

#### Does TikTok Trending Hashtags And Videos Scraper require a TikTok account or login?

No. It reads TikTok's live public Creative Center endpoint and public hashtag video pages with an anonymous browser session — there's no username, password, or session-cookie field anywhere in the input.

#### How many hashtags and videos can I extract in one run?

`maxHashtags` collects up to 100 hashtag rows per run, and `maxVideosPerHashtag` fetches up to 50 linked videos per hashtag — up to 5,000 video rows in a single run at the maximums.

#### What happens if a hashtag has no videos or TikTok returns an empty feed?

The hashtag row is still pushed with its ranking data; the video fetch retries once on a fresh browser session, and if TikTok's tag page still returns nothing, no video rows are added for that hashtag — never fabricated placeholders.

#### Can I scrape multiple TikTok hashtags at once?

Yes. `maxHashtags` returns multiple ranked hashtags per run, and `hashtagsToAnalyze` accepts an array of your own hashtags to resolve against the live trending data in Custom Hashtag Analytics mode.

#### Does this scraper work with Claude, ChatGPT, and other AI agent tools?

Yes. It's callable as a plain HTTP endpoint through the Apify API from any agent framework, and it's reachable through Apify's Actors MCP Server (`https://mcp.apify.com`) for MCP-compatible clients like Claude Desktop and Claude Code.

#### Does this scraper return data in a format LLMs can use directly?

Yes. It returns typed, normalized JSON with consistent field names across runs — no HTML parsing or CSS selectors. Pass the dataset directly to an LLM, index it into a vector store, or feed it to an agent tool.

#### What happens when TikTok changes its layout or anti-bot system?

The Actor is maintained and its output schema stays stable across TikTok changes, because it reads TikTok's own network responses rather than parsing the visual page. No specific fix turnaround time is promised.

#### Can I use this scraper without managing proxies or browser infrastructure?

Yes. The Actor runs its own headless Chromium browser via Playwright and handles session seeding and retries; proxy use is optional and only needed if you want requests routed through Apify proxy.

#### Which fields work best for AI training data and RAG indexing?

For RAG, index `caption` (video text), `hashtag_name`, and `aiTopics` as the high-information text fields. For training data, `rank`, `video_views`, `publish_cnt`, and the engagement counts (`diggCount`, `playCount`, `commentCount`, `shareCount`) are the most consistently structured numeric fields across every run, returned as typed primitives rather than strings.

### Related scrapers

| Scraper Name | What it extracts |
| --- | --- |
| Trending Videos Insights and Branded Hashtag Views & Likes | TikTok Top Ads cost/CTR analytics |
| TikTok Trending Videos Scraper With Author Profile | Trending/direct-URL videos with full creator profile |
| Instagram Hashtag Scraper | Instagram posts and reels by hashtag |
| Google Trends Scraper | Interest-over-time popularity timelines |
| YouTube Comments Scraper : AI Sentiment Analytics | Comments with AI sentiment and spam heuristics |

### Your feedback

Found a bug or missing a field? Let us know so we can take a look — feedback like this is what keeps this Actor accurate as TikTok's site changes.

# Actor input Schema

## `resultMode` (type: `string`):

Choose what the scraper should return. 🏆 Trending Ranking = the hashtag list only. 📊 Ranking + Analytics = list with per-hashtag trend/creator analytics. 🔬 Custom Hashtag Analytics = analytics for your own hashtag list (see 'Hashtags To Analyze' below). Base-compat: also accepts the legacy `result_type` key.

## `targetCountry` (type: `string`):

Pick a country (or 🌐 All for global trends). Base-compat: also accepts the legacy `country` key.

## `trendingWindow` (type: `string`):

Time window for the trending ranking. Used by 🏆 Trending Ranking and 📊 Ranking + Analytics. Base-compat: also accepts `top100_period`.

## `analyticsWindow` (type: `string`):

Time window for analytics curves (trend history/engagement growth). Used by 🔬 Custom Hashtag Analytics. Base-compat: also accepts `analytics_period`.

## `industryCategory` (type: `string`):

Narrow the trending ranking by industry. Leave on 🌐 All Industries to skip filtering. Base-compat: also accepts `top100_industry`.

## `onlyNewEntries` (type: `boolean`):

Enable to return only hashtags that newly entered the ranking in the chosen period. Base-compat: also accepts `top100_new_on_board`.

## `maxHashtags` (type: `integer`):

Top-level cap on how many trending hashtags to collect (this is the parent-row cap; video children are counted separately below). Example: 20 → up to 20 hashtag rows. Base-compat: also accepts `total_hashtags`.

## `hashtagsToAnalyze` (type: `array`):

Your own hashtags (without the #) to fetch analytics for. Only used when Result Mode = 🔬 Custom Hashtag Analytics. If a hashtag isn't currently trending in the selected country/period, TikTok returns no analytics for it. Base-compat: also accepts `hashtag_list`.

## `fetchTopVideos` (type: `boolean`):

When ON, the actor opens each hashtag's TikTok page and captures its live video feed (up to the cap below) as linked child rows. Turn OFF for a hashtag-only run (faster).

## `maxVideosPerHashtag` (type: `integer`):

Cap on how many top videos to fetch PER hashtag (children are additional to Max Hashtags, not counted against it). Example: Max Hashtags=20 + Max Videos Per Hashtag=5 → up to 20 hashtag rows plus up to 100 linked video rows. 0 = no videos.

## `enableAiAnalysis` (type: `boolean`):

When ON (and an API key is supplied below), each video caption fetched by 'Fetch Top Videos Per Hashtag' is classified for sentiment/topics/language.

## `aiModel` (type: `string`):

Provider auto-detected from the name: claude-*=Anthropic, gpt-*/o1/o3=OpenAI, gemini-*=Google, grok-*=xAI, deepseek-*=DeepSeek, sonar*=Perplexity, mistral-\*=Mistral. Cheaper mini/flash/haiku models are recommended for classification.

## `aiApiKey` (type: `string`):

Your own API key for the selected AI provider (Anthropic/OpenAI/Google/xAI/DeepSeek/Perplexity/Mistral). Required only when AI Caption Analysis is ON. Never logged or stored.

## `proxyConfiguration` (type: `object`):

Choose which proxies to use. By default no proxy is used.

## Actor input object example

```json
{
  "resultMode": "top100",
  "targetCountry": "ALL",
  "trendingWindow": "7",
  "analyticsWindow": "30",
  "onlyNewEntries": false,
  "maxHashtags": 20,
  "hashtagsToAnalyze": [],
  "fetchTopVideos": true,
  "maxVideosPerHashtag": 5,
  "enableAiAnalysis": false,
  "aiModel": "claude-haiku-4-5",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "resultMode": "top100",
    "targetCountry": "ALL",
    "trendingWindow": "7",
    "analyticsWindow": "30",
    "industryCategory": "",
    "maxHashtags": 20,
    "hashtagsToAnalyze": [],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapeengine/tiktok-trending-hashtags-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "resultMode": "top100",
    "targetCountry": "ALL",
    "trendingWindow": "7",
    "analyticsWindow": "30",
    "industryCategory": "",
    "maxHashtags": 20,
    "hashtagsToAnalyze": [],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("scrapeengine/tiktok-trending-hashtags-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "resultMode": "top100",
  "targetCountry": "ALL",
  "trendingWindow": "7",
  "analyticsWindow": "30",
  "industryCategory": "",
  "maxHashtags": 20,
  "hashtagsToAnalyze": [],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call scrapeengine/tiktok-trending-hashtags-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=scrapeengine/tiktok-trending-hashtags-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/9JO66hf5iTOhAQGXy/builds/EH74UnqedJ3OXFtYx/openapi.json