# TikTok Trending Hashtags Scraper — Rank, Views & Creators (`crawloop/tiktok-trending-hashtags-scraper`) Actor

Scrape TikTok trending hashtags from Creative Center: rank, views, post count, popularity curve, and top creators. 27 countries and 7/30/90-day windows. No login — export JSON via API, Python, Node.js, or MCP.

- **URL**: https://apify.com/crawloop/tiktok-trending-hashtags-scraper.md
- **Developed by:** [Andrej Kiva](https://apify.com/crawloop) (community)
- **Categories:** Social media, AI, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.99 / 1,000 trending hashtags

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## 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 & Creators

> Unofficial tool for publicly accessible TikTok Creative Center trend data. TikTok and related trademarks belong to their respective owners. Not affiliated with, sponsored by, or endorsed by TikTok or ByteDance. Provided for informational use only; users must comply with applicable terms and laws.

| Social discovery | Product launches |
| :--- | :--- |
| **TikTok Trending Hashtags Scraper** ◄── you are here | [Product Hunt Scraper](https://apify.com/crawloop/producthunt-scraper) |
| [Bluesky Scraper](https://apify.com/crawloop/bluesky-scraper) | Launches, reviews, comments, leaderboards |

**TikTok trending hashtags scraper** and **TikTok API alternative** — extract TikTok's own Creative Center ranking as structured JSON: hashtag, rank, video views, post count, industry labels, a **popularity curve**, and the **top creators** driving it. Filter by country and 7 / 30 / 90-day window. No TikTok login, no cookies, no API token.

Scrape TikTok hashtags with **Python**, **Node.js**, **cURL**, or **MCP** / AI assistants. Export JSON, CSV, or Excel from the dataset.

### When to use

- See what is ranking on TikTok this week in a specific market
- Compare 7-day breakouts vs 90-day staying power
- Sweep all 27 published countries in one run
- Feed hashtag + creator handles into a briefing, dashboard, or agent workflow

### When not to use

- You need **more than 3 hashtags per country and window** — that is TikTok's public cap (`totalCount: 3`, `hasMore: false`). There is no page 2.
- You want videos under a hashtag, comments, or profiles — this Actor only returns the Creative Center **board**.
- You send `period=120` expecting a 120-day chart. TikTok silently serves **7 days** on that value; this Actor remaps 120/180 to **90** instead.

### Key features

- **Official board, not a guess** — Remix `loaderData` / `dehydratedState` from Creative Center Trends → Hashtag
- **27 countries** — the exact `hashtagCountry` list TikTok publishes (US, GB, DE, BR, JP, …)
- **7 / 30 / 90-day windows** — echoed `period` and `countryCode` written back on every row
- **Curve + momentum** — 7-point popularity series plus `rising` / `fading` / `flat`
- **Top creators** — handle, nickname, follower count, profile URL
- **Honest empty-run** — HTTP 200 under 200 bytes or a missing `popular/hashtags` query is treated as a fingerprint gate, not "no trends today"
- **No login** — residential proxy recommended on Apify

### Input

| Parameter | Description |
|-----------|-------------|
| `countries` | ISO codes to scrape (default `US`). Closed list of 27 markets |
| `allCountries` | Sweep every published market in one run |
| `period` | `7`, `30`, or `90` (default `7`) |
| `periods` | Extra windows merged with `period` (e.g. 7+30+90) |
| `maxItems` | Dataset cap for the whole run (default 100) |
| `concurrency` | Parallel slices, 1–12 (default 6) |
| `proxyConfiguration` | Apify RESIDENTIAL recommended |

United States, this week:

```json
{
  "countries": ["US"],
  "period": "7",
  "maxItems": 10,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "US"
  }
}
```

All 27 countries, three windows:

```json
{
  "allCountries": true,
  "periods": ["7", "30", "90"],
  "maxItems": 250,
  "concurrency": 8
}
```

### Output

One dataset row per hashtag × country × window. TikTok serves **3 rows per slice**.

| Field | Description |
|-------|-------------|
| `type` | Always `hashtag_trend` |
| `hashtagId` / `hashtagName` | TikTok id and name without `#` |
| `hashtagUrl` | Tag page on tiktok.com |
| `rank` | Board position (1 = top) |
| `country` / `countryName` / `period` | Market and window TikTok actually served |
| `countryRequested` / `periodRequested` | What you asked for |
| `countryFallbackApplied` / `periodAliasApplied` | True when served ≠ requested |
| `views` / `publishCount` | Window video views and post count |
| `industryIds` / `industryLabels` | Creative Center industry classification |
| `popularityCurve` | `[{ timestamp, value }]` 0–100 series |
| `momentum` / `trendDirection` | Last-third vs first-third of the curve (`rising` / `fading` / `flat`) |
| `topCreators` | `creatorId`, `handle`, `nickname`, `followerCount`, `avatarUrl`, `profileUrl` |
| `link` / `sourceUrl` | Creative Center slice URL |
| `scrapedAt` | ISO timestamp |

```json
{
  "type": "hashtag_trend",
  "hashtagId": "497780",
  "hashtagName": "perezhilton",
  "hashtagUrl": "https://www.tiktok.com/tag/perezhilton",
  "rank": 1,
  "country": "US",
  "countryName": "United States",
  "period": 7,
  "publishCount": 11897,
  "views": 332625639,
  "industryLabels": ["News and Entertainment"],
  "trendDirection": "fading",
  "momentum": -76.21,
  "topCreators": [
    {
      "handle": "lvlyrxy",
      "nickname": "LVLYRXY",
      "followerCount": 3759,
      "profileUrl": "https://www.tiktok.com/@lvlyrxy"
    }
  ]
}
```

### Use cases

- Weekly trend brief for a social team (US + GB + DE, 7-day window)
- Spot low-competition reach: high `views`, lower `publishCount`
- Catch fading vs rising tags from `trendDirection` before you brief creators
- Multi-market sweep: same hashtag appearing in many `country` rows is a cross-border signal
- Hand `topCreators[].handle` to a profile/enrichment workflow
- Give an AI assistant the board via **MCP** and ask for a one-page briefing

### Integration examples

#### Node.js

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('crawloop/tiktok-trending-hashtags-scraper').call({
  countries: ['US'],
  period: '7',
  maxItems: 10,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient(token)
run = client.actor("crawloop/tiktok-trending-hashtags-scraper").call(
    run_input={"countries": ["US"], "period": "7", "maxItems": 10}
)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item.get("rank"), item.get("hashtagName"), item.get("views"))
```

#### cURL

```bash
curl "https://api.apify.com/v2/acts/crawloop~tiktok-trending-hashtags-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"countries":["US"],"period":"7","maxItems":10}'
```

### MCP and AI assistants

Use this Actor from AI tools via [Apify MCP](https://docs.apify.com/platform/integrations/mcp). Connect your Apify account, then call `crawloop/tiktok-trending-hashtags-scraper`.

Example prompts:

- "Run TikTok Trending Hashtags Scraper for US, 7-day window, and return rank, hashtag, views, and trendDirection"
- "Sweep GB, DE, and FR for 30-day TikTok trending hashtags and list rising tags"
- "Get all 27 countries for the 7-day TikTok hashtag board and summarize cross-market repeats, then check Bluesky mentions with Bluesky Scraper"

### Suite next step

For open social listening on another network, run [Bluesky Scraper](https://apify.com/crawloop/bluesky-scraper) (posts, search, monitor). For launch-day product buzz, use [Product Hunt Scraper](https://apify.com/crawloop/producthunt-scraper).

### FAQ

**Do I need a TikTok or ads account?**\
No. The Actor reads the public Creative Center trends board. Nothing to log into.

**Is this a TikTok API?**\
It is a **TikTok API alternative** for the public trending-hashtag board — no official TikTok Research API key required.

**Why only 3 hashtags?**\
That is TikTok's public payload: `pagination.limit` and `totalCount` are 3, `hasMore` is false. Sweep countries and windows for volume — 27 × 3 windows = up to 243 rows.

**Can I scrape TikTok hashtags with Python or Node.js?**\
Yes. Use the Apify client examples above, or call the Actor from an AI assistant via MCP.

**Why did a run fail with an empty dataset?**\
Creative Center is TLS-fingerprint gated. A plain HTTP client gets HTTP 200 and an empty `dehydratedState`. Enable Apify RESIDENTIAL proxy. This Actor fails the run instead of billing a silent empty board.

**Is 120 days supported?**\
Not on this surface. Sending 120 to TikTok is aliased to 7. This Actor remaps 120/180 to 90 so you get the long window you likely wanted, and sets `periodAliasApplied`.

**Can I get related hashtags or videos?**\
Not from this board route. Each row is the ranking + curve + creators TikTok puts on the Trends → Hashtag page.

### Related Actors

| Actor | Role |
| :--- | :--- |
| TikTok Trending Hashtags Scraper ◄── you are here | Creative Center hashtag ranking |
| [Bluesky Scraper](https://apify.com/crawloop/bluesky-scraper) | Posts, profiles, search, monitor |
| [Product Hunt Scraper](https://apify.com/crawloop/producthunt-scraper) | Product launches and reviews |

# Actor input Schema

## `countries` (type: `array`):

Markets whose trending-hashtag board to scrape. TikTok publishes this board for 27 countries only. Ignored when Sweep all countries is on. Default: United States.

## `allCountries` (type: `boolean`):

Fetch every market TikTok publishes on this board (27 countries). Overrides Countries. A full sweep with all three windows is 81 requests and at most 243 rows before maxItems.

## `period` (type: `string`):

Look-back window for the ranking. 7 = breaking now, 30 = this month, 90 = staying power. TikTok does not publish 120 here — it silently serves 7 if you send 120 raw; this Actor remaps 120/180 to 90 instead.

## `periods` (type: `array`):

Optional extra windows to fetch in the same run (merged with Time window). Use this for 7+30+90 in one dataset.

## `maxItems` (type: `integer`):

Hard cap on dataset rows for the whole run. TikTok serves 3 hashtags per country × window, so 100 covers a full 27-country × 1-window sweep.

## `concurrency` (type: `integer`):

Parallel country × window requests (1–12). Lower it if you see fingerprint blocks.

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

Apify RESIDENTIAL proxy is recommended. Creative Center answers a non-impersonated or datacenter client with HTTP 200 and an empty board.

## Actor input object example

```json
{
  "countries": [
    "US"
  ],
  "allCountries": false,
  "period": "7",
  "periods": [],
  "maxItems": 100,
  "concurrency": 6,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Default dataset items (one row per hashtag × country × window).

# 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 = {
    "countries": [
        "US"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawloop/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 = {
    "countries": ["US"],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

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

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

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

```

## CLI example

```bash
echo '{
  "countries": [
    "US"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call crawloop/tiktok-trending-hashtags-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,crawloop/tiktok-trending-hashtags-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/5fe3Vwa2qLCKyHcPB/builds/PgoNj1N268LGpI5vQ/openapi.json