# TikTok Hashtag Trends Scraper - Trending Hashtags & History API (`trendingtiktoksongs/tiktok-trending-hashtags-history`) Actor

Track TikTok trends with popular hashtag rankings from Creative Center in the US, UK, Germany, France, Brazil, Canada and Australia. Export 100 trending hashtags per 7/30-day chart with post and view counts, trend curves, top creators and history as JSON, CSV or API. No TikTok login. Dates may lag.

- **URL**: https://apify.com/trendingtiktoksongs/tiktok-trending-hashtags-history.md
- **Developed by:** [Trending TikTok Data](https://apify.com/trendingtiktoksongs) (community)
- **Categories:** Social media, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 hashtag observations

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

Find trending TikTok hashtags by country. Export hashtag rankings, reported post and view counts, popularity curves and top creators as JSON or CSV. Use the latest chart to plan content, or compare stored dates to follow ranking changes. No TikTok login is required.

### TikTok hashtag trends data you can export

- Up to 100 hashtags per country and chart window, with hashtag links and exact string IDs.
- Reported post/view counts, industry IDs and daily popularity index curves.
- Top creators with handles, profile links, follower counts and exact string IDs when provided.
- Stored ranking history, rank changes and new chart entries when consecutive source dates are available.

### Trending TikTok hashtags by country: 7-day and 30-day charts

United States (`US`), United Kingdom (`GB`), Germany (`DE`), France (`FR`), Brazil (`BR`), Canada (`CA`) and Australia (`AU`) each support 7-day and 30-day charts. The country describes the ranking market; a listed creator can be from another country.

The chart window and history range are separate. `periodDays: 30` selects the 30-day ranking chart. `days: 7` in history mode exports observations from the last seven calendar dates in our archive.

### Export popular TikTok hashtags: quick start

```json
{"country":"US","mode":"latest","periodDays":7,"maxRows":10}
```

For ranking history:

```json
{"country":"DE","mode":"history","periodDays":7,"days":7,"maxRows":700}
```

For a fixed history range, provide both `fromDate` and `toDate` as UTC `YYYY-MM-DD` dates and omit `days`. A range can cover up to 30 calendar days. The maximum export is 5,000 observations. Unknown input fields and unsupported countries/windows are rejected.

### TikTok hashtag rankings: coverage and field meanings

Data comes from TikTok Creative Center hashtag charts, collected centrally and stored by reporting date. Customer runs export the archive. The source reporting date can lag the current day; the output reports both `source_snapshot_date` and `collected_at`.

Stored history begins with our first collected reporting date for each country/window. A popularity curve contains source-provided index points, not past complete chart snapshots. The `OUTPUT` record reports available and missing calendar dates. Empty history returns no billed results; it does not invent historical rankings.

`reported_posts` and `reported_views` retain the counts reported for the selected chart. Popularity curve values are normalized indices from 0 to 100, not daily post/view totals. Source ranks can contain gaps and are preserved. `rank_change` is positive when a hashtag moves up, and is null without the same hashtag on the preceding calendar source date. `new_to_chart` is null when that preceding chart is missing. Counts may change as ranking windows roll forward.

This Actor covers ranked hashtags in the supported charts. It does not retrieve every TikTok hashtag or promise real-time trend detection. Demographics and related-video samples are not part of this version. Profile pictures and external links may expire.

### TikTok hashtag scraper results and pricing

Each hashtag on one country/window/source date written to the default dataset is one result. Export the dataset as JSON or CSV. The `OUTPUT` record contains coverage, delivered row counts and limit information.

Price: **$3 per 1,000 delivered observations**, plus **$0.00005 per Actor start**, with platform usage included. A 100-row chart costs $0.30005. `maxRows` and the run's spending limit cap delivered results. Coverage summaries and missing dates are not billed as results.

# Actor input Schema

## `country` (type: `string`):

Country of the hashtag rankings. Creator countries may differ.

## `mode` (type: `string`):

Latest exports one archived source date; history exports only dates we have collected.

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

Enter 7 or 30. The ranking window is separate from stored history days.

## `maxRows` (type: `integer`):

One hashtag on one source date is one billed result. Latest contains 100 hashtags per country/window; history can contain more.

## `days` (type: `integer`):

History mode only. Omit for seven calendar days ending on the latest archived source date. Missing dates are reported.

## `fromDate` (type: `string`):

Optional fixed history range; requires toDate. Omit days when using dates.

## `toDate` (type: `string`):

Last source date of a fixed history range. Requires fromDate; dates use UTC.

## Actor input object example

```json
{
  "country": "US",
  "mode": "latest",
  "periodDays": 7,
  "maxRows": 10
}
```

# Actor output Schema

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

No description

## `coverage` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("trendingtiktoksongs/tiktok-trending-hashtags-history").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("trendingtiktoksongs/tiktok-trending-hashtags-history").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 '{}' |
apify call trendingtiktoksongs/tiktok-trending-hashtags-history --silent --output-dataset

```

## MCP server setup

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

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/Bw1KuDmRx2PubVEjf/builds/4pceWkg89a1y4vWt0/openapi.json