# TikTok Hashtag Trends Scraper (`axiomworks/tiktok-trending-hashtags-scraper`) Actor

Scrape trending TikTok hashtags from Creative Center for a country and a 7, 30 or 90 day window: rank, industry, post and view counts, daily popularity curve, optional top creators and a computed momentum score. Without login each ranking shows its top 3, so about 48 hashtags max.

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

## Pricing

from $0.89 / 1,000 results

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## TikTok Hashtag Trends Scraper

**Returns:** one row per trending TikTok hashtag with rank, hashtag, posts, views, momentum, trend, industry, industryNames and popularityCurve.
**Input:** `{"countryCode": "US", "periodDays": 7, "maxItems": 20, "industries": ["Games", "Travel"]}`
**Best for:** content calendars, spotting rising hashtags by industry, and country-by-country trend reports.

```json
{
  "id": "US-7-8824",
  "rank": 1,
  "hashtag": "winterwonderland",
  "posts": 1503,
  "views": 3853725,
  "momentum": 7.02,
  "trend": "rising",
  "industry": "Travel",
  "industryNames": ["Travel"],
  "country": "US",
  "periodDays": 7
}
```

### What does TikTok Hashtag Trends Scraper do?

TikTok Hashtag Trends Scraper collects the trending-hashtag rankings that TikTok publishes on its public Creative Center and adds a momentum score computed from each hashtag's popularity curve. It needs no login. This is an independent tool and is not affiliated with or endorsed by TikTok.

Without a login, each Creative Center ranking shows its top 3 hashtags. The Actor reads the overall ranking ("All") first, then the site's 15 industry rankings, such as Education, Beauty & Personal Care, Games, Food & Beverage, Travel and Tech & Electronics. It keeps every hashtag once and stops at `maxItems`. That gives up to about 48 distinct hashtags for a given country and period.

Typical uses:

- Spotting hashtags that are rising, not just large, by sorting on `momentum`.
- Comparing what trends in different countries or over 7, 30 and 90 days.
- Finding which hashtags lead in a given industry.
- Feeding a content calendar, a trend report or a dashboard with a fresh list every day.

### What data can you get?

Each record in the dataset has these fields:

| Field | Meaning |
| --- | --- |
| `id` | Stable id: `country-periodDays-hashtagId`, for example `US-7-7675592944980033556` |
| `sourceUrl` | Creative Center page for the country and period |
| `rank` | Position (1-3) within the ranking named in `industry` |
| `industry` | `All` for the overall ranking, otherwise the industry name |
| `hashtag`, `hashtagId` | Hashtag text (without `#`) and TikTok's id |
| `posts`, `views` | Posts and video views the site reports for the period |
| `popularityCurve` | Daily `{timestamp, value}` points (value 0-100, timestamp as an integer in Unix seconds) |
| `momentum` | Mean of the last 3 curve values divided by the mean of the first 3, rounded to 2 decimals. Above 1 means the hashtag is rising. |
| `url` | `https://www.tiktok.com/tag/<hashtag>` |
| `country`, `periodDays` | Country and window the data is for |
| `trend` | `rising` (momentum 1.1 or more), `fading` (0.9 or less) or `steady`, derived from `momentum` |
| `industryNames` | Every industry the site tags the hashtag with (list of names) |
| `category` | Niche picked by an AI processor: music, comedy, product, news, challenge or other. `null` unless `enrich` is on and the processor answers |
| `topCreators` | Handle, nickname and follower count of the top creators the site lists (only when `includeTopCreators` is on) |

The momentum score is worked out by the Actor, not by TikTok. In the example under Output, the curve starts 0, 89.48, 99.13 and ends 97.94, 99.39, 100, so the last three average about 99.11 and the first three about 62.87, which gives 1.58. A value near 1 means a flat curve, and a value below 1 means the hashtag is fading.

### How to use TikTok Hashtag Trends Scraper

1. Open the Actor in Apify Console and go to the Input tab.
2. Enter a two-letter `countryCode`, for example `US` or `GB`.
3. Pick a `periodDays` window of 7, 30 or 90.
4. Set `maxItems` to the number of hashtags you want. Up to about 48 are available per country and period.
5. Optionally set `minMomentum` to keep only rising hashtags, switch `includeTopCreators` on, or switch `enrich` on if you want an AI category (costs extra per hashtag).
6. Click Start. A 20-hashtag run usually takes under a minute, because requests are spaced 5 seconds apart to be polite to the site.
7. Open the Output tab to view the table, or download the dataset as JSON, CSV or Excel.

Invalid input stops the run straight away with an error message that says what to change. The Actor never hangs on bad input.

### Input

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `countryCode` | string | `US` | One of 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. Other codes stop the run with an error listing the valid ones. Each record shows the code in `country`. |
| `periodDays` | integer | 7 | 7, 30 or 90. 120 is accepted but returns the 90-day window, and records show `periodDays: 90`. Other values fail the run. |
| `maxItems` | integer | 20 | Maximum number of hashtags. Each hashtag appears once. You get fewer records if the rankings run out or `minMomentum` filters some out; the run log then says how many were available. |
| `minMomentum` | number | 0 | Keep only hashtags whose `momentum` is at least this value. |
| `industries` | array | empty | Only read the listed rankings, for example `["Games", "Travel"]` (names are case-insensitive; `All` is the overall ranking). Empty reads every ranking. Unknown names fail the run with the list of valid names. |
| `includeTopCreators` | boolean | false | When on, each record has a `topCreators` list. It can be empty if the site lists no creators for that hashtag. It is prefilled on in the Console form. |
| `enrich` | boolean | false | Adds a `category` chosen by a third-party AI processor. Costs extra per categorised hashtag. When off, or when the processor does not answer, `category` is `null`. |

Example input:

```json
{
  "countryCode": "US",
  "periodDays": 7,
  "maxItems": 20,
  "minMomentum": 0,
  "industries": ["Games", "Travel"],
  "includeTopCreators": true,
  "enrich": false
}
```

### Output

This is the first record from a local run with the input above (with `enrich` off, so `category` is `null`):

```json
{
  "id": "US-7-7675592944980033556",
  "sourceUrl": "https://ads.tiktok.com/creative/creativeCenter/trends/hashtag?countryCode=US&period=7&region=US",
  "rank": 1,
  "hashtag": "citytastetest",
  "hashtagId": "7675592944980033556",
  "posts": 805308,
  "views": 666868302,
  "popularityCurve": [
    {
      "timestamp": 1789948800,
      "value": 0
    },
    {
      "timestamp": 1790035200,
      "value": 89.48
    },
    {
      "timestamp": 1790121600,
      "value": 99.13
    },
    {
      "timestamp": 1790208000,
      "value": 98.49
    },
    {
      "timestamp": 1790294400,
      "value": 97.94
    },
    {
      "timestamp": 1790380800,
      "value": 99.38
    },
    {
      "timestamp": 1790467200,
      "value": 100
    }
  ],
  "momentum": 1.58,
  "url": "https://www.tiktok.com/tag/citytastetest",
  "country": "US",
  "periodDays": 7,
  "industry": "All",
  "category": null,
  "topCreators": [
    {
      "handle": "funny27clips",
      "nickname": "luki",
      "followers": 121352
    },
    {
      "handle": "funnyblack88",
      "nickname": "funny😘🤭clips",
      "followers": 387394
    },
    {
      "handle": "jeenyjef1",
      "nickname": "jeenyjef1",
      "followers": 18220
    }
  ]
}
```

The run log lists how many hashtags each ranking contributed and ends with a line such as `Done: 20 hashtags`. Hashtags come out in the order the rankings are read: the overall ranking first, then each industry.

### How much does it cost?

The Actor uses pay-per-event pricing. You are charged per result: each hashtag saved to the dataset is one result. If you switch on the optional AI category, each hashtag that actually received a category is charged as an extra. If the processor is unavailable, hashtags are still returned and no extra is charged. The AI category is off by default. Current prices are on the Pricing tab of the Actor page. Because the number of hashtags is capped by `maxItems`, you can bound the cost of a run before you start it.

### Use with the API

You can start the Actor from code and read the dataset when it finishes.

Python:

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")
run = client.actor("axiomworks/tiktok-trending-hashtags-scraper").call(
    run_input={"countryCode": "US", "periodDays": 7, "maxItems": 20}
)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["hashtag"], item["momentum"])
```

JavaScript:

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

const client = new ApifyClient({ token: '<YOUR_API_TOKEN>' });
const run = await client.actor('axiomworks/tiktok-trending-hashtags-scraper').call({
    countryCode: 'US',
    periodDays: 7,
    maxItems: 20,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
process.stdout.write(items.map((i) => `${i.hashtag} ${i.momentum}`).join("\n") + "\n");
```

cURL:

```bash
curl -X POST "https://api.apify.com/v2/acts/axiomworks~tiktok-trending-hashtags-scraper/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"countryCode": "US", "periodDays": 7, "maxItems": 20}'
```

You can also run the Actor on a schedule, send results to a webhook, or connect it to tools such as Make, Zapier or Google Sheets through the Apify integrations.

### Use with AI agents (MCP)

You can call this Actor from any MCP-compatible assistant through the Apify MCP server. Add this to your client configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/?tools=axiomworks/tiktok-trending-hashtags-scraper"
    }
  }
}
```

Example prompts:

- "Get the 20 trending TikTok hashtags in the US over 7 days and list the five with the highest momentum."
- "Which hashtags are trending in Germany over 30 days? Keep only those with momentum above 1.2."
- "Compare the top hashtags in Japan and South Korea for the last 7 days."

### FAQ

**Why do I get at most about 48 hashtags?**
Without a login, each Creative Center ranking shows only its top 3 hashtags. The Actor combines the overall ranking with 15 industry rankings and removes duplicates.

**Why did I get fewer hashtags than `maxItems`?**
Either the rankings ran out or `minMomentum` filtered some hashtags out. The run log says how many were available.

**Why is `category` null?**
`enrich` is off (the default), or the AI processor did not answer for that hashtag. The hashtag is still returned.

**Where does `category` come from?**
From a third-party AI processor (TypeSafe AI), which receives only the hashtag text, and only when `enrich` is on.

**Why is `topCreators` empty for some hashtags?**
The site lists no creators for that hashtag.

**What does `periodDays: 120` do?**
It returns the 90-day window, and the records show `periodDays: 90`.

**Is momentum a TikTok metric?**
No. It is computed by the Actor from the popularity curve, as described in the field table.

**Does the Actor use a proxy?**
It uses Apify Proxy automatically and retries once without a proxy.

### Is it legal to scrape TikTok?

The Actor reads only rankings that TikTok shows publicly on its Creative Center without a login. It does not collect private data or bypass any access control. The data is aggregate trend data plus the public handles of the top creators listed on the page, when you turn that option on. You are responsible for using the results in line with the laws that apply to you, including data-protection rules, and with TikTok's terms of service. This Actor is not affiliated with or endorsed by TikTok.

### Feedback

If a field is missing, a country stops working or the numbers look wrong, open an issue from the Actor's Issues tab with the input you used and the run link. Reports like that help the most.

# Actor input Schema

## `countryCode` (type: `string`):

Two-letter country code of the ranking, e.g. US, GB, DE, JP. Must be one of the listed codes.

## `periodDays` (type: `integer`):

Ranking window in days: 7, 30 or 90 (120 is treated as 90). Other values fail the run. The value used is in each record's periodDays field.

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

Maximum number of hashtags to return. The overall ranking comes first, followed by the per-industry rankings, with duplicates removed.

## `minMomentum` (type: `number`):

Only return hashtags whose momentum score is at least this value (0 = no filter).

## `industries` (type: `array`):

Only read these industry rankings, e.g. \["Games", "Travel"]. Names: All, Education, Vehicle & Transportation, Baby, Kids & Maternity, Beauty & Personal Care, Tech & Electronics, Travel, Household Products, Pets, Home Improvement, Apparel & Accessories, News & Entertainment, Games, Food & Beverage, Sports & Outdoor, Health. Empty = all rankings.

## `includeTopCreators` (type: `boolean`):

Add the top creators the site lists for each hashtag (handle, nickname, follower count).

## `enrich` (type: `boolean`):

Add a category (music, comedy, product, news, challenge or other) chosen by a third-party AI processor. Costs extra per categorised hashtag (billed as an extra enriched-result event). Default false.

## Actor input object example

```json
{
  "countryCode": "US",
  "periodDays": 7,
  "maxItems": 20,
  "minMomentum": 0,
  "industries": [],
  "includeTopCreators": true,
  "enrich": false
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# 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 = {
    "countryCode": "US",
    "periodDays": 7,
    "maxItems": 20,
    "includeTopCreators": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("axiomworks/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 = {
    "countryCode": "US",
    "periodDays": 7,
    "maxItems": 20,
    "includeTopCreators": True,
}

# Run the Actor and wait for it to finish
run = client.actor("axiomworks/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 '{
  "countryCode": "US",
  "periodDays": 7,
  "maxItems": 20,
  "includeTopCreators": true
}' |
apify call axiomworks/tiktok-trending-hashtags-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,axiomworks/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/zw7TZGSMPlHvOvA4D/builds/1HFRC3GS8lwmCGWZz/openapi.json