# TikTok Hashtag Scraper (`insights_data/tiktok-hashtag-scraper`) Actor

Scrolling TikTok hashtags by hand misses trends. Scrape any hashtag in bulk: videos with captions, views, likes, comments, shares, saves, author stats, music, covers and video links, plus optional transcripts. Export JSON, CSV or Excel. No login.

- **URL**: https://apify.com/insights_data/tiktok-hashtag-scraper.md
- **Developed by:** [Insights Data](https://apify.com/insights_data) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

### 🏷️ What is TikTok Hashtag Scraper?

**TikTok Hashtag Scraper** collects the public TikTok hashtag videos posted under the hashtags you give it, for marketers, creator scouts, trend researchers and data teams. Just enter one or more hashtags and click **Start**: you need no code, no TikTok account, no login and no cookies.

For every video you get the caption, posting date, plays, likes, comments, shares, saves, the author's profile stats, the sound, cover and video links, an engagement rate and, if you want, the spoken-word transcript. It is a TikTok scraper that starts from hashtags, and it saves everything to a table you can download.

- **Creator scouting:** see who posts under a niche hashtag, with followers, total likes and verified badge. This is often the first step of a TikTok influencer search.
- **TikTok hashtag analytics:** get plays, likes, comments, shares, saves and engagement rate for every video under a branded hashtag.
- **Trend tracking:** run the same hashtags every week and compare the totals and the new videos.
- **Content research:** read the captions and transcripts of videos under a hashtag.

#### What can TikTok Hashtag Scraper do?

- 🏷️ **Read hashtags in any format**: plain names (`cooking`), names with `#` (`#recipes`) or hashtag links (`https://www.tiktok.com/tag/booktok`)
- 🔍 **Save only real matches**: every saved video carries the hashtag you asked for, with no duplicates per hashtag
- 🎯 **Filter videos** by **Posted within** and **Minimum plays**; videos that are filtered out are not billed
- 📝 **Built-in TikTok transcript extractor**: adds the spoken words from TikTok's own captions, with the transcript language
- 📊 **Get hashtag totals**: the total views and total videos TikTok reports for each hashtag
- ⚡ **See live results**: videos appear in the Output tab while the run is still going
- 🔌 **Use it as a TikTok scraper API**: start and schedule runs from your code, get webhooks, connect integrations, and export to JSON, CSV, Excel, XML or HTML

***

### 🗂️ What data can TikTok Hashtag Scraper extract?

You can extract TikTok hashtag data with one row per video. Each row also names the hashtag that found the video and carries that hashtag's totals.

| Data | Fields |
|---|---|
| 🎬 Video | `id`, `text` (caption), `webVideoUrl`, `isAd`, `isSlideshow`, `language` (caption language) |
| 📅 Posting time | `createTimeISO` (date and time in UTC) and `createTime` (the same time as a Unix timestamp in seconds) |
| 👁️ Plays | `playCount` |
| ❤️ Engagement counts | `diggCount` (likes), `commentCount`, `shareCount`, `collectCount` (saves) |
| 📈 Engagement rate | `engagementRate` (%) |
| 👤 Author | `authorMeta` (see the table below) |
| 🎵 Music | `musicMeta`: `musicName`, `musicAuthor`, `musicOriginal`, `musicAlbum`, `playUrl` (audio link), `coverMediumUrl`, `musicId` |
| 🖼️ Media | `videoMeta`: `height`, `width`, `duration` (seconds), `coverUrl`, `originalCoverUrl`, `definition`, `format`, `downloadAddr`, `subtitleLinks`; plus `mediaUrls` and `slideshowImages` |
| 🏷️ Hashtags and mentions | `hashtags` (every hashtag on the video: `id`, `name`, `title`), `mentions` (@accounts in the caption) |
| 📝 Transcript | `transcript`, `transcriptLanguage` |
| 📊 Hashtag totals | `hashtag` (the searched hashtag), `hashtagTotalViews`, `hashtagTotalVideos` |

The author fields in `authorMeta`:

| Field | Meaning |
|---|---|
| 👤 `name`, `nickName`, `profileUrl` | Username, display name and profile link |
| 🪪 `signature` | The author's bio |
| ✔️ `verified`, `privateAccount` | Verified badge and private-account flag |
| 👥 `fans`, `following` | Followers and accounts followed |
| ❤️ `heart` | Total likes the author has received |
| 🎬 `video` | Number of videos the author has posted |
| 👍 `digg` | Number of videos the author has liked |
| 🆔 `id`, `avatar` | TikTok user ID and profile picture link |

The TikTok engagement rate in `engagementRate` is (likes + comments + shares + saves) / plays x 100, rounded to two decimals.

> **Note:** Some fields can be empty. `transcript` stays `null` when transcripts are off or the video has no TikTok captions. `engagementRate` is `null` when there is no play count. Media links (`mediaUrls`, `downloadAddr`, `playUrl`, covers) are temporary TikTok links that expire after some time, so save what you need soon after the run.

#### What data can't TikTok Hashtag Scraper extract?

- Video, cover or audio **files**. You get links only, and nothing is downloaded.
- The text of comments and replies. You get `commentCount` only.
- Private videos or anything that needs a TikTok login.

For comment text, use [TikTok Comments & Replies Scraper](https://apify.com/insights_data/tiktok-comments-replies-scraper).

***

### 🚀 How to scrape TikTok hashtags

These steps show how to scrape TikTok videos for any hashtag, even if you've never extracted data from the web before.

1. [Create a free Apify account](https://console.apify.com/sign-up) using your email.
2. Open [TikTok Hashtag Scraper](https://apify.com/insights_data/tiktok-hashtag-scraper).
3. Add your hashtags in **Hashtags to scrape**, one per line, and set **Max videos per hashtag**.
4. Click **Start**. The run log shows saved videos as they come in, and the videos appear in the **Output** tab while the run is going.
5. When the run finishes, download your data in JSON, CSV, Excel, XML or HTML from the Output tab, or go to **Storage → Datasets → Export**.

***

### 💲 How much does it cost to scrape TikTok?

TikTok Hashtag Scraper uses **pay-per-event** pricing. Your bill has three parts:

1. **Results:** you pay for each video saved to the dataset. The price depends on your Apify plan (see the table).
2. **Start fee:** one small fee of **$0.0002** each time a run starts. It is $0.00005 per GB of memory, and this Actor needs more memory than most Actors, so its default is 4 GB.
3. **Platform usage:** the Apify compute the run uses, paid by you on top of the events. It is billed for the whole time the run takes, so the amount depends on your run. Do a small test run and check the cost on the run page.

| Apify plan | Price per video | Price per 1,000 videos |
|---|---|---|
| 🟢 Free | $0.002 | $2.00 |
| 🔵 Starter | $0.0018 | $1.80 |
| 🟣 Scale | $0.0016 | $1.60 |
| ⚫ Business and higher | $0.0015 | $1.50 |

The plan discount applies to the video price only. The start fee is the same on every plan, and platform usage is billed at your Apify plan's own rates.

Videos that your filters leave out are not saved and not billed. Error rows for hashtags that fail are not billed either.

| Example | Results | Start fee | Platform usage |
|---|---|---|---|
| 🟢 Free plan, 1 hashtag, 10 videos | 10 x $0.002 = $0.02 | $0.0002 | See the run page |
| 🔵 Starter plan, 1,000 videos | 1,000 x $0.0018 = $1.80 | $0.0002 | See the run page |
| 🟣 Scale plan, 1,000 videos | 1,000 x $0.0016 = $1.60 | $0.0002 | See the run page |
| ⚫ Business plan, 1,000 videos | 1,000 x $0.0015 = $1.50 | $0.0002 | See the run page |

To control spending, set a **maximum charge limit** in the run options when you start a run. When the limit is reached, the run stops and keeps the videos it already saved. See the [pricing tab](https://apify.com/insights_data/tiktok-hashtag-scraper/pricing) for the live prices.

#### Is scraping TikTok free?

Yes, you can try this TikTok scraper free of charge on the [Apify Free plan](https://apify.com/pricing), which gives you $5 in monthly credit. Free-plan runs work the same as paid runs. The credit is used up by the events plus the platform usage together, so set a maximum charge limit when you start a run and do a small test run first.

***

### ⬇️ TikTok Hashtag Scraper input

To run TikTok Hashtag Scraper, you only need **one or more hashtags**. Everything else is optional. Set the input in the Actor's form, or send it as JSON through the API (the API name of each setting is shown in brackets).

#### Settings most people change

| Setting in the form | Default | What it does |
|---|---|---|
| 🏷️ Hashtags to scrape (`urls`) | required | One hashtag per line: `cooking`, `#recipes` or `https://www.tiktok.com/tag/booktok`. Plain hashtags work; you don't need links |
| 🎬 Max videos per hashtag (`resultsPerPage`) | `10` | Maximum videos saved for each hashtag. `0` = no per-hashtag maximum |
| 📅 Posted within (`postedWithin`) | Any time | Keep only videos posted in this period |
| 👁️ Minimum plays (`minPlays`) | `0` | Keep only videos with at least this many plays |
| 📝 Subtitles and transcript (`downloadSubtitlesOptions`) | Don't add transcripts | Choose *Add transcripts (when the video has captions)* to add transcripts |
| 🌐 Proxy (`proxyConfiguration`) | no proxy | Optional. The run switches to Apify Proxy automatically when needed |

Here's an example that collects up to 10 videos for #cooking:

```json
{
  "urls": ["cooking"],
  "resultsPerPage": 10
}
```

See the [input tab](https://apify.com/insights_data/tiktok-hashtag-scraper/input-schema) for a full description of all fields.

#### Hashtags to scrape

Write each hashtag with or without the `#` sign, or paste a TikTok hashtag link. Duplicate hashtags are scraped once. Profile and video links are not hashtags, so they are ignored, with a note in the log.

- ✅ Good: `cooking`, `#recipes`, `https://www.tiktok.com/tag/booktok`
- ❌ Bad: `https://www.tiktok.com/@chef/video/123` (a video link, not a hashtag)

#### Posted within

Pick a value from the list (Any time, Last 24 hours, Last 7 days, Last 2 weeks, Last month, Last 3 months, Last 6 months, Last year) or type your own: a number with `h` (hours), `d` (days), `w` (weeks), `m` (months of 30 days) or `y` (years of 365 days), such as `10d`. You can also type a start date like `2026-01-31`: videos posted from 00:00 UTC on that date onwards are kept.

- ✅ Good: `7d`, `24h`, `2026-01-31`
- ❌ Bad: `last week`

> ⚠️ If the value can't be read, for example an impossible date like `2026-02-30`, the run stops before scraping and asks you to check your input.

#### Subtitles and transcript

Choose *Add transcripts (when the video has captions)* to get the spoken words of each video as text in `transcript`, with its language in `transcriptLanguage`. Videos without TikTok captions keep an empty transcript. When a video has captions in several languages, the English captions are used when available; you can't pick another language. The caption links of every language are listed in `videoMeta.subtitleLinks` whatever you choose here.

***

### ⬆️ TikTok Hashtag Scraper output

Results are stored in a dataset, which you find in the **Output** or **Storage** tab. Each run builds a TikTok hashtag dataset with one row per video. You can view it as a table or JSON, pick only the fields you need, and download it in JSON, CSV, Excel, XML or HTML.

The Output tab shows the videos in these views: **Overview**, **Videos**, **Engagement**, **Authors**, **Music**, **Media**, **Transcripts** and **Hashtag stats**. It also has a **Hashtags** tab with one row per input hashtag.

#### JSON example

One result for the input example above. It is shortened: the real `hashtags` array lists every hashtag on the video.

```json
{
  "id": "7686329816190094599",
  "text": "Fish curry #miniaturecooking #asmr #shorts #cooking #food",
  "createTime": 1789613129,
  "createTimeISO": "2026-09-17T02:45:29.000Z",
  "isAd": false,
  "authorMeta": {
    "name": "miniature_doll_cooking",
    "profileUrl": "https://www.tiktok.com/@miniature_doll_cooking",
    "verified": false,
    "fans": 3835,
    "heart": 24300,
    "video": 44
  },
  "musicMeta": { "musicName": "original sound", "musicOriginal": true },
  "webVideoUrl": "https://www.tiktok.com/@miniature_doll_cooking/video/7686329816190094599",
  "videoMeta": { "height": 1024, "width": 576, "duration": 32, "definition": "540p", "format": "mp4" },
  "diggCount": 947,
  "shareCount": 25,
  "playCount": 106800,
  "collectCount": 248,
  "commentCount": 39,
  "hashtags": [{ "id": "18973", "name": "cooking", "title": "" }],
  "isSlideshow": false,
  "language": "en",
  "engagementRate": 1.18,
  "transcript": null,
  "hashtag": "cooking",
  "hashtagTotalViews": 556027939755,
  "hashtagTotalVideos": 19359325
}
```

#### Hashtags tab

The **Hashtags** tab in the Output gives you TikTok hashtag stats and the result of the run, with one row per input hashtag. These rows are not billed.

| Field | Meaning |
|---|---|
| 🏷️ `hashtag`, `title`, `hashtagId`, `hashtagUrl` | The cleaned hashtag, its name on TikTok, its ID and its link |
| 📊 `totalViews`, `totalVideos` | Total views and total videos TikTok reports for the hashtag |
| 🎬 `videosSaved`, `matchingVideosSeen` | Videos saved in this run, and matching videos found before your filters |
| 🔁 `searchPasses`, `transcriptsAdded` | Search passes run for the hashtag, and videos that got a transcript |
| 🚦 `status` | What happened to the hashtag (see below) |
| ⚠️ `error`, `errorCode` | Filled when the hashtag did not finish |

#### What the status means

| Status | What happened |
|---|---|
| ✅ `done` | The hashtag was collected |
| ⏸️ `stopped early` | The run stopped while collecting this hashtag, because your maximum charge limit was reached. The videos saved before that are kept |
| ⏭️ `skipped` | The hashtag was not started, because the run had already stopped for that reason. It has no error code |
| ❌ `failed` | The hashtag could not be collected. See the error code |

#### Error codes and error rows

A failed hashtag also adds one row to the main video dataset, with `input` (the hashtag), `error` and `errorCode`, so it doesn't go missing silently. These rows are not billed. Video rows have no `errorCode`, so to leave the error rows out of a spreadsheet, filter out the rows where `errorCode` has a value.

| errorCode | Meaning and what to do |
|---|---|
| ⚠️ `HASHTAG_NOT_FOUND` | TikTok has no hashtag with that name. Check the spelling |
| ⚠️ `SCRAPE_FAILED` | TikTok did not answer for this hashtag. Try again later, or choose a proxy in the **Proxy** setting |

If no video could be collected and every hashtag failed, the run ends as failed, with a message on the run page.

***

### 💡 TikTok Hashtag Scraper tips and advanced usage

#### How many videos can you scrape with TikTok Hashtag Scraper?

It depends on the hashtag. **Max videos per hashtag** sets your maximum. With `0` there is no per-hashtag maximum, but the search for each hashtag ends when no new matching videos turn up, or when the Actor's own search limit for that hashtag is reached. The number also depends on what TikTok shows to a visitor without a login, which changes over time. A quick test run shows what to expect for your hashtags.

#### How to get faster or cheaper results

- Keep **Max videos per hashtag** low for a first test, then raise it.
- Use **Posted within** and **Minimum plays** to leave out videos you don't need. Videos that are left out are not billed.
- Turn on transcripts only when you need them. They have no separate charge, but they add work to the run.
- Add several hashtags to one run so you pay the start fee once.

#### Use it as a TikTok hashtag tracker

Schedule a daily or weekly run in Apify Console with **Posted within** set to `Last 24 hours` or `Last 7 days`. Each run adds the newest videos and the current hashtag totals, so over time you build your own TikTok hashtag trend data. Load the dataset into a spreadsheet or the TikTok hashtag analytics tool you already use.

#### Known issues

- Media links (`mediaUrls`, `downloadAddr`, `playUrl`, covers) expire after some time. Save what you need soon after the run.
- Videos without TikTok captions have no transcript.
- If TikTok does not answer at the start, the first video can take a little longer while the run switches to Apify Proxy.
- Videos that have no play count in TikTok's data are not removed by **Minimum plays**.

***

### 🔌 TikTok Hashtag Scraper integrations and API

#### Can I use TikTok Hashtag Scraper as a TikTok hashtag API?

Yes. The [Apify API](https://docs.apify.com/api/v2) lets you start runs, schedule them and fetch results from your own code. Use the `apify-client` [NPM package](https://apify.com/insights_data/tiktok-hashtag-scraper/api/javascript) for Node.js or the `apify-client` [PyPI package](https://apify.com/insights_data/tiktok-hashtag-scraper/api/python) for Python. The [API tab](https://apify.com/insights_data/tiktok-hashtag-scraper/api) has ready-to-use code.

#### How to scrape TikTok with Python

Here is a short TikTok scraper Python example with the official Apify client. Install it with `pip install apify-client`, then run:

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")
run = client.actor("insights_data/tiktok-hashtag-scraper").call(
    run_input={"urls": ["cooking"], "resultsPerPage": 10}
)

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

You get the same fields as in the Output tab.

#### Can I integrate TikTok Hashtag Scraper with other apps?

Yes. Connect it through [Apify integrations](https://apify.com/integrations) with **Make, Zapier, Slack, Google Sheets, Google Drive, Airbyte, GitHub, LangChain** and others. Use [webhooks](https://docs.apify.com/integrations/webhooks) to trigger an action when a run finishes. For example, send each week's new videos for your campaign hashtag to a Google Sheet.

#### Can I use TikTok Hashtag Scraper with AI agents (MCP)?

Yes. Connect it to Claude and other AI assistants through the Apify MCP server. Open the [MCP tab](https://apify.com/insights_data/tiktok-hashtag-scraper/api/mcp) for setup steps.

***

### 🧩 Other TikTok and short-video scrapers

These Actors from the same author cover data this one doesn't, such as the videos of a single account or the text of comments.

- 👤 [TikTok Profile Scraper](https://apify.com/insights_data/tiktok-profile-scraper): scrape any TikTok profile's videos, reposts, stories and playlists with views, likes, comments, shares, music, hashtags and author stats. Optional followers, comments, transcripts and media downloads.
- 💬 [TikTok Comments & Replies Scraper](https://apify.com/insights_data/tiktok-comments-replies-scraper): extract comments and replies from TikTok videos, photo posts and whole profiles, with text, likes, reply counts, dates, mentions and commenter details.
- 🎬 [Douyin 抖音 Video Scraper - Metadata](https://apify.com/insights_data/douyin-video-scraper-metadata): scrape Douyin videos and image posts from links, share links or IDs, with caption, author, music, likes, comments, shares, hashtags and post date.

***

### ❓ FAQ

#### Is it legal to scrape TikTok?

Scraping publicly available data is generally legal, but how you use it matters. TikTok Hashtag Scraper only collects public videos that anyone can see without logging in. Respect personal data rules such as the GDPR, only collect personal data when you have a legitimate reason, and take [TikTok's Terms of Service](https://www.tiktok.com/legal/page/us/terms-of-service/en) and the copyright of videos and music into account. This is not legal advice.

#### How does TikTok Hashtag Scraper work?

It works like you browsing a hashtag on TikTok, only faster. For each hashtag, it checks that the hashtag exists and reads its totals. Then it looks through the public videos tagged with it, keeps only the ones that really carry the hashtag and pass your filters, adds transcripts if you asked for them, and saves each batch to your dataset right away.

#### Is TikTok Hashtag Scraper a general TikTok data scraper?

No. It is a TikTok hashtag extractor, so it starts from hashtags only. For one account's posts, [TikTok Profile Scraper](https://apify.com/insights_data/tiktok-profile-scraper) is the TikTok video scraper to use. For comment text, use TikTok Comments & Replies Scraper.

#### Can I use it as a TikTok video data scraper?

Yes, for videos found through hashtags. Each row has the video's stats, author, sound and media links. To start from a profile instead, use TikTok Profile Scraper.

#### Is TikTok Hashtag Scraper a TikTok hashtag search tool?

Partly. It searches the hashtags you give it and saves the matching videos, but it doesn't suggest or rank hashtags for you.

#### Can I run a TikTok hashtag search without account login?

Yes. You don't need a TikTok account, login or cookies. The Actor reads the public data that any visitor can see.

#### How is TikTok Hashtag Scraper different from copying videos by hand?

| Feature | TikTok Hashtag Scraper | Browsing and copying by hand |
|---|---|---|
| Many hashtags at once | Yes | No |
| Plays, likes, comments, shares and saves in one table | Yes | No |
| Author stats and sound for each video | Yes | No |
| Date and plays filters | Yes | No |
| Export to CSV or Excel, API and schedules | Yes | No |

#### Why scrape TikTok hashtag videos?

You can use it as a TikTok hashtag research tool for:

- **TikTok hashtag research:** see which videos, creators and sounds appear under a hashtag, and how often they are played.
- **TikTok trend research:** compare the totals and new videos of several hashtags from run to run, and follow TikTok hashtag trends over time.
- **TikTok social listening:** check what people post under your brand or product hashtags.
- **TikTok hashtag analysis for campaigns:** measure how a branded hashtag performs with plays, likes, shares and engagement rate.

#### Why am I getting fewer results than expected?

1. **Max videos per hashtag** is `10` by default. Raise it, or set it to `0`.
2. **Posted within** and **Minimum plays** leave out videos that don't match.
3. TikTok shows a limited number of videos to visitors without a login, and the number varies by hashtag.
4. Check the **Hashtags** tab: `failed` with `HASHTAG_NOT_FOUND` means the hashtag doesn't exist on TikTok.
5. If you set a maximum charge limit, the run stops when it is reached.

#### Is it a TikTok video downloader or a TikTok video link scraper?

A link scraper. You get the video page link (`webVideoUrl`), a playable stream link (`mediaUrls`), the `downloadAddr`, the cover links and the slideshow image links. No files are downloaded, and the media links are temporary.

#### Is there a TikTok hashtag exporter to Excel?

Yes. Download the dataset as Excel (or CSV, JSON, XML or HTML) from the Output tab, or go to **Storage → Datasets → Export**.

#### Can I check TikTok hashtag views with it?

Yes. Each run records the total views and total videos that TikTok shows for the hashtag at that moment, in `hashtagTotalViews`, `hashtagTotalVideos` and the **Hashtags** tab. It isn't a live TikTok hashtag views counter, but scheduled runs show how the totals change.

#### Can I get a TikTok transcript download with the videos?

Yes, as text in the dataset, not as a separate file. Set **Subtitles and transcript** to *Add transcripts (when the video has captions)*.

#### Is there a TikTok video scraper Python library?

You don't need one for hashtag videos. Install `apify-client` and use the snippet in the Python section under Integrations and API.

#### What TikTok engagement rate formula does it use?

`engagementRate` = (likes + comments + shares + saves) / plays x 100, rounded to two decimals. It is empty when a video has no play count.

***

### 📧 Support and feedback

We keep improving TikTok Hashtag Scraper. Found a bug or want a new field? Please create an issue on the [Issues tab](https://apify.com/insights_data/tiktok-hashtag-scraper/issues/open).

Need a **custom solution** or more data? Contact us at hello.insights.data@gmail.com.

Built and maintained by [Insights Data](https://apify.com/insights_data).

# Actor input Schema

## `urls` (type: `array`):

One hashtag per line. Write it with or without the # sign (cooking, #recipes) or paste a TikTok hashtag link such as https://www.tiktok.com/tag/cooking. Add as many as you like – each one is scraped in turn.

## `resultsPerPage` (type: `integer`):

Maximum number of videos saved for every hashtag. 0 = as many as TikTok shows without a login (it varies by hashtag).

## `postedWithin` (type: `string`):

Only keep videos posted in this period. Pick a value or type your own: a number with h (hours), d (days), w (weeks), m (months) or y (years), e.g. 10d, or a start date like 2026-01-31. all = no date filter.

## `minPlays` (type: `integer`):

Only keep videos with at least this many plays (views). 0 = no minimum.

## `downloadSubtitlesOptions` (type: `string`):

Choose whether to add the transcript text (and its language) to every video that has TikTok captions. Videos without captions keep an empty transcript. Caption links are always listed in the video details, whatever you pick here.

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

Leave on no proxy for the automatic mode: if TikTok blocks the run it moves to a datacenter proxy, then to a residential proxy, and keeps that for the rest of the run. Pick a proxy here to start with it instead.

## Actor input object example

```json
{
  "urls": [
    "cooking",
    "#recipes",
    "https://www.tiktok.com/tag/booktok"
  ],
  "resultsPerPage": 10,
  "postedWithin": "all",
  "minPlays": 10000,
  "downloadSubtitlesOptions": "NEVER_DOWNLOAD_SUBTITLES",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `overview` (type: `string`):

The main facts of every video.

## `videos` (type: `string`):

Post details: caption, type, language, hashtags and mentions.

## `engagement` (type: `string`):

Plays, likes, comments, shares, saves and engagement rate.

## `authors` (type: `string`):

Who posted each video, with profile stats.

## `music` (type: `string`):

The sound used in each video.

## `media` (type: `string`):

Video size, length, quality, cover and media links.

## `transcripts` (type: `string`):

Spoken words of each video (when transcripts are on and TikTok has captions).

## `hashtag_stats` (type: `string`):

Which hashtag found each video and that hashtag's size on TikTok.

## `hashtags` (type: `string`):

One row per input hashtag with TikTok totals and run status.

# 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 = {
    "urls": [
        "cooking",
        "#recipes"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("insights_data/tiktok-hashtag-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 = {
    "urls": [
        "cooking",
        "#recipes",
    ],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("insights_data/tiktok-hashtag-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 '{
  "urls": [
    "cooking",
    "#recipes"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call insights_data/tiktok-hashtag-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,insights_data/tiktok-hashtag-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/c5QgctDfivGTG2NiB/builds/QaxIKeqmZnd5TY6HW/openapi.json