# TikTok Hashtag Scraper for Public Videos (`datascraperes/tiktok-hashtag-video-scraper`) Actor

Collect public TikTok videos by hashtag with captions, video URLs, views, likes, comments, shares, creators, hashtags and dates. Explore trends, discover content, analyze creators and monitor social media. Export clean results to JSON, CSV or Excel, paying only for videos returned.

- **URL**: https://apify.com/datascraperes/tiktok-hashtag-video-scraper.md
- **Developed by:** [DataScraperES](https://apify.com/datascraperes) (community)
- **Categories:** Social media, Videos
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 1,000 public tiktok video records

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/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 Hashtag Scraper for Public Videos

Collect public TikTok videos by hashtag and receive clean, structured records with captions, video links, engagement statistics, creator information, hashtags and dates. Use the results for trend research, content discovery, creator analysis and social media monitoring.

### Why use this Actor?

- Find public videos from one or many TikTok hashtags.
- Enter hashtag names, names with `#`, or public TikTok hashtag URLs.
- Receive one clear result for each available video.
- Review captions, video links, publication dates, hashtags and engagement data.
- See creator usernames and public profile details when TikTok provides them.
- Export your results from Apify as JSON, CSV, Excel or other available formats.
- Pay only for videos that are actually returned and saved.

### What you can collect

Every video result can include the following public information:

| Information | What it contains |
| --- | --- |
| Video | Video ID, public TikTok URL, caption and duration |
| Publication | Creation timestamp and a readable publication date |
| Engagement | Views, likes, comments and shares when available |
| Hashtags | Hashtags detected on the video |
| Creator | Username, display name and verification status when available |
| Hashtag context | Hashtag name, public hashtag URL, description and public counters |
| Collection status | Number requested, number returned and whether more public results were available |

TikTok may not provide every field for every video. Missing optional information is left empty instead of being invented.

### How to use it

1. Add one or more hashtags to the **TikTok hashtags** field.
2. Choose how many videos you want per hashtag and for the whole run, if you want to change the defaults.
3. Start the Actor and open the Dataset when the run finishes.
4. Review, filter or export the results in the format you need.

No TikTok account is required. Only public TikTok information is collected.

### Input options

#### TikTok hashtags

Add hashtag names such as `marketing`, `#fitness`, or a public URL such as `https://www.tiktok.com/tag/beauty`. Duplicate values are removed automatically.

#### Include public video results

Enabled by default. Returns one Dataset row for every available public video. Disable it only when you need the public hashtag information without collecting video rows.

#### Maximum videos per hashtag

Sets the maximum number of video results requested for each hashtag. The maximum allowed value is 1,000.

#### Maximum videos per run

Sets a safety limit for the complete run across all hashtags. The maximum allowed value is 5,000. You are charged only for the video rows that are actually saved.

#### Additional public details

Optional. Includes additional public fields when TikTok makes them available. The standard result remains focused on the information most useful for analysis and exports.

The Actor automatically manages request pacing and waiting time so you do not need to configure technical settings.

### Results

The Dataset is organized around video results. This makes it easy to download the data, filter it in a spreadsheet, or use it in a social media analysis workflow.

Each video row includes a collection summary. The `stopReason` value explains why collection ended:

- `MAX_LIMIT`: the requested maximum was reached.
- `SOURCE_EXHAUSTED`: TikTok did not expose more public videos for that hashtag in the current result.
- `RATE_LIMITED`: TikTok temporarily limited the request; partial results may still be available.

The public video list can be much smaller than the counter shown on a hashtag page. For example, a hashtag may show millions of videos while the current public result only exposes a smaller set. The Actor reports the available results and never creates or charges unavailable videos.

### Pricing

The price is **$0.001 per video result**, equivalent to **$1 per 1,000 videos**.

There is no video charge for:

- A hashtag that returns no videos.
- An input or source error.
- A metadata-only run with video collection disabled.
- A video that was not saved to the Dataset.

The final amount depends on the number of video rows actually returned, not on the number shown in TikTok's hashtag counter or the maximum you selected.

### Use cases

- Discover popular content in a niche.
- Monitor hashtags for campaigns and brands.
- Research content ideas and recurring themes.
- Compare public engagement across hashtags.
- Find creators publishing around a topic.
- Build datasets for social media, marketing and trend analysis.

### Important notes

- Only public TikTok information is collected.
- Private, deleted or unavailable videos cannot be returned.
- TikTok results and counters can change over time and by region.
- A maximum of 1,000 videos per hashtag and 5,000 videos per run can be selected.
- The Actor collects video information and public links; it does not download video files.
- Results should be used responsibly and in accordance with TikTok's terms and applicable law.

### Frequently asked questions

#### Can I enter a hashtag with or without `#`?

Yes. Both `marketing` and `#marketing` are accepted. Public TikTok `/tag/` URLs are also accepted.

#### Can I collect several hashtags in one run?

Yes. Add as many hashtags as you need within the input limit. Duplicate hashtags are automatically removed.

#### Will I always receive the maximum number selected?

No. The maximum is an upper limit. The number of available public videos depends on TikTok's current public results for that hashtag.

#### What happens when a hashtag has no available videos?

The Actor keeps a clear status record for the hashtag and does not charge a video event.

#### Are videos downloaded?

No. The results include public TikTok links and video information, but not downloaded video files.

#### Can I export the results?

Yes. Use the Dataset export options in Apify to download the results in the format that best fits your workflow.

#### Is a TikTok login needed?

No. The Actor is designed for public TikTok information and does not require your TikTok account.

# Actor input Schema

## `hashtags` (type: `array`):

Examples: #marketing, marketing, or https://www.tiktok.com/tag/marketing.

## `includeVideos` (type: `boolean`):

Returns one Dataset record per public video. Each returned video costs $0.001; this does not request or download video media.

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

Maximum number of public video summaries to collect with cursor pagination. The Actor never downloads video media.

## `maxTotalVideos` (type: `integer`):

Global safety limit across all requested hashtags. You are charged only for videos actually saved.

## `includeRaw` (type: `boolean`):

Includes additional public information when TikTok makes it available. The standard result remains focused on the fields most useful for analysis and export.

## Actor input object example

```json
{
  "hashtags": [
    "#marketing"
  ],
  "includeVideos": true,
  "maxVideosPerHashtag": 100,
  "maxTotalVideos": 100,
  "includeRaw": false
}
```

# Actor output Schema

## `results` (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 = {
    "hashtags": [
        "#marketing"
    ],
    "includeVideos": true,
    "maxVideosPerHashtag": 100,
    "maxTotalVideos": 100,
    "includeRaw": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("datascraperes/tiktok-hashtag-video-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 = {
    "hashtags": ["#marketing"],
    "includeVideos": True,
    "maxVideosPerHashtag": 100,
    "maxTotalVideos": 100,
    "includeRaw": False,
}

# Run the Actor and wait for it to finish
run = client.actor("datascraperes/tiktok-hashtag-video-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 '{
  "hashtags": [
    "#marketing"
  ],
  "includeVideos": true,
  "maxVideosPerHashtag": 100,
  "maxTotalVideos": 100,
  "includeRaw": false
}' |
apify call datascraperes/tiktok-hashtag-video-scraper --silent --output-dataset

```

## MCP server setup

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