# TikTok Hashtag Scraper — Stats & Top Videos (`toolzerhub/tiktok-hashtag-scraper`) Actor

Fetch TikTok hashtag metadata by name or collect current top videos as separate rows with hashtag context, captions, statistics, and music information.

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

## Pricing

from $1.40 / 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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use 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

**Turn a TikTok hashtag name into one structured metadata record.**

TikTok Hashtag Scraper looks up a public hashtag by name and returns its TikTok challenge ID, identity fields, and available statistics. Current top videos stay optional, so a metadata check does not automatically become a video-collection run.

### Enter the hashtag, not an internal ID

Enter `cats` rather than `#cats` or a numeric challenge ID. Choose a region only when you enable Add Hashtag Videos; the region affects that optional video request.

#### Look up a hashtag

Enter a hashtag name without #. Metadata mode returns one hashtag row; Add Hashtag Videos returns one row per current top video with hashtag context.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tag_name` | string | Yes | TikTok hashtag name without the # symbol. |
| `region` | string | No | Two-letter region code affecting search/feed results, e.g. US, GB, JP. |
| `enrichHashtagVideos` | boolean | No | Return each current top video as a separate row with hashtag context. One extra request. |

```json
{
  "tag_name": "cats",
  "region": "US",
  "enrichHashtagVideos": false
}
````

### Choose a metadata dataset or a video dataset

With Add Hashtag Videos off, the Actor saves one hashtag metadata row. With it on, the Actor saves only video rows—one row per returned video—with `tag_name`, `ch_id`, and `ch_info` repeated on every row. It never hides the videos inside a `hashtag_videos` array.

Both modes expose `hashtag_video_count` and `hashtag_view_count` as top-level columns. Each video also keeps the upstream fields and adds stable aliases such as `description`, `stats`, and `music_info`, so JSON users retain the original payload while CSV and table users get predictable columns. Counts can be absent or zero when the public source does not provide them.

#### 🏷️ Hashtag identity

| Field | Type | Description |
| --- | --- | --- |
| `tag_name` | mixed | TikTok hashtag name used for the lookup. |
| `ch_id` | mixed | TikTok hashtag/challenge ID. |
| `hashtag_video_count` | mixed | Number of videos reported for the hashtag, when available. |
| `hashtag_view_count` | mixed | Total hashtag views reported by TikTok, when available. |
| `ch_info` | object | Hashtag info, when available. |

#### 🎬 Video rows when enabled

| Field | Type | Description |
| --- | --- | --- |
| `aweme_id` | string | TikTok video ID. |
| `description` | mixed | Video caption or user bio, when available. |
| `create_time` | mixed | Creation timestamp, when available. |
| `stats` | object | Engagement stats (likes/comments/shares/plays or followers/following/hearts), when available. |
| `music_info` | object | Music/sound info attached to a video, when available. |

```json
{
  "tag_name": "cats",
  "ch_id": "5216",
  "hashtag_video_count": 0,
  "hashtag_view_count": 424700000000,
  "ch_info": {
    "challenge": {
      "id": "5216",
      "title": "cats"
    },
    "stats": {
      "videoCount": 0,
      "viewCount": 424700000000
    }
  }
}
```

### Pay for the rows you request

Metadata mode saves and charges one hashtag row. Add Hashtag Videos mode saves and charges one row per returned video, plus one add-on event after the video request succeeds.

Apify's free credits may cover a one-hashtag metadata test before enabling the optional video request.

Video mode returns a video-only dataset with hashtag context repeated on every row; current tier prices are shown on the Actor Pricing tab.

### Responsible hashtag-data use

This Actor extracts publicly available TikTok content. It should not be used to collect private user data. Make sure your use case complies with applicable privacy laws, TikTok's terms, and your own legal obligations. If you are unsure, consult a qualified lawyer.

### Run this Actor from code

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_API_TOKEN")
run = client.actor("toolzerhub/tiktok-hashtag-scraper").call(run_input={
    "tag_name": "cats",
    "region": "US",
    "enrichHashtagVideos": false
})

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

#### Node.js

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

const client = new ApifyClient({ token: "YOUR_APIFY_API_TOKEN" });
const run = await client.actor("toolzerhub/tiktok-hashtag-scraper").call({
  "tag_name": "cats",
  "region": "US",
  "enrichHashtagVideos": false
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Search for videos, or look up a sound

- [TikTok Video Search Scraper — Full Details](https://apify.com/toolzerhub/tiktok-video-search-scraper) — Search public TikTok videos by keyword with automatic pagination. Export video IDs, captions, timestamps, statistics, and music data, with optional full-detail enrichment per result.
- [TikTok Sound & Music Scraper — Track Videos](https://apify.com/toolzerhub/tiktok-sound-scraper) — Fetch TikTok sound information by music ID or collect videos using that sound as separate rows with music context, captions, and engagement statistics.
- [Bulk TikTok Video Scraper — URLs, Stats & Music](https://apify.com/toolzerhub/tiktok-video-scraper) — Fetch multiple public TikTok videos from IDs, full video URLs, or vt/vm share links. Export one row per video with captions, timestamps, engagement statistics, and music metadata.

### ToolzerHub support

Use the Issues tab on the Actor page for bug reports, missing fields, and feature requests.

Contact: contact@toolzerhub.com

# Actor input Schema

## `tag_name` (type: `string`):

TikTok hashtag name without the # symbol.

## `region` (type: `string`):

Two-letter region code affecting search/feed results, e.g. US, GB, JP.

## `enrichHashtagVideos` (type: `boolean`):

Return each current top video as a separate row with hashtag context. One extra request.

## Actor input object example

```json
{
  "tag_name": "cats",
  "region": "US",
  "enrichHashtagVideos": false
}
```

# Actor output Schema

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

Dataset containing all scraped data

# 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 = {
    "tag_name": "cats",
    "region": "US"
};

// Run the Actor and wait for it to finish
const run = await client.actor("toolzerhub/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 = {
    "tag_name": "cats",
    "region": "US",
}

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

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

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

```

## CLI example

```bash
echo '{
  "tag_name": "cats",
  "region": "US"
}' |
apify call toolzerhub/tiktok-hashtag-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=toolzerhub/tiktok-hashtag-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "TikTok Hashtag Scraper — Stats & Top Videos",
        "description": "Fetch TikTok hashtag metadata by name or collect current top videos as separate rows with hashtag context, captions, statistics, and music information.",
        "version": "0.1",
        "x-build-id": "lwt5U0BYNYdpGsqAi"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/toolzerhub~tiktok-hashtag-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-toolzerhub-tiktok-hashtag-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/toolzerhub~tiktok-hashtag-scraper/runs": {
            "post": {
                "operationId": "runs-sync-toolzerhub-tiktok-hashtag-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/toolzerhub~tiktok-hashtag-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-toolzerhub-tiktok-hashtag-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "tag_name"
                ],
                "properties": {
                    "tag_name": {
                        "title": "Hashtag",
                        "type": "string",
                        "description": "TikTok hashtag name without the # symbol."
                    },
                    "region": {
                        "title": "Region",
                        "type": "string",
                        "description": "Two-letter region code affecting search/feed results, e.g. US, GB, JP.",
                        "default": "US"
                    },
                    "enrichHashtagVideos": {
                        "title": "Add Hashtag Videos",
                        "type": "boolean",
                        "description": "Return each current top video as a separate row with hashtag context. One extra request.",
                        "default": false
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```