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

Scrape public TikTok hashtag videos, captions, creators, and engagement metrics for trend research and influencer discovery.

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

## Pricing

from $6.05 / 1,000 tiktok video saveds

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.md):

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

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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

## TikTok Hashtag Scraper

Collect public TikTok hashtag videos, captions, creator profiles, and engagement metrics from hashtag pages such as `#booktok`, `#fitness`, or `#skincare`.

### What does TikTok Hashtag Scraper do?

TikTok Hashtag Scraper extracts public video rows from TikTok hashtag pages and saves clean, export-ready data to an Apify dataset.

It is built for teams that need a quick view of what videos are ranking for a hashtag, which creators are visible, and how engagement compares across campaigns or niches.

### Who is it for?

- 📈 Social media analysts tracking campaign hashtags
- 🧑‍💼 Influencer marketing teams discovering creators
- 📰 Trend researchers monitoring TikTok topics
- 🛍️ Ecommerce teams watching product hashtags
- 🏢 Agencies reporting hashtag performance to clients

### Why use it?

Manual TikTok research is slow. This actor turns hashtag pages into structured rows you can filter, export, enrich, and send to dashboards.

### What data can I extract?

| Field | Description |
| --- | --- |
| `hashtag` | Source hashtag |
| `videoId` | TikTok video ID |
| `videoUrl` | Public video URL |
| `caption` | Video caption text |
| `authorUsername` | Creator username |
| `authorProfileUrl` | Creator profile URL |
| `authorDisplayName` | Creator display name |
| `createTime` | Published timestamp when available |
| `duration` | Video duration in seconds |
| `playCount` | View count |
| `diggCount` | Like count |
| `commentCount` | Comment count |
| `shareCount` | Share count |
| `coverUrl` | Cover image URL |
| `musicTitle` | Music title |
| `scrapedAt` | Time the row was collected |

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

The actor uses pay-per-event pricing: a small start fee plus a per-video result fee. The exact live price is shown on the Apify Store run screen before you start a paid run.

### How to use TikTok Hashtag Scraper

1. Open the actor on Apify.
2. Add one or more hashtags, with or without `#`.
3. Set the maximum videos per hashtag.
4. Keep the default residential proxy unless you know another proxy works for your account.
5. Run the actor.
6. Download results as JSON, CSV, Excel, XML, or HTML.

### Input example

```json
{
  "hashtags": ["booktok", "skincare"],
  "maxItemsPerHashtag": 20,
  "sortMode": "top",
  "includeVideoDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "US"
  }
}
````

### Output example

```json
{
  "hashtag": "booktok",
  "videoId": "7223827494913215786",
  "videoUrl": "https://www.tiktok.com/@jenna_bushhager/video/7223827494913215786",
  "caption": "#WorldBookDay is 4/23...",
  "authorUsername": "jenna_bushhager",
  "authorProfileUrl": "https://www.tiktok.com/@jenna_bushhager",
  "authorDisplayName": "Jenna Bush Hager",
  "createTime": "2023-04-19T18:20:30.000Z",
  "duration": 30,
  "playCount": 39100,
  "diggCount": 993,
  "commentCount": 36,
  "shareCount": 35,
  "coverUrl": "https://...",
  "musicTitle": "original sound",
  "scrapedAt": "2026-06-18T00:00:00.000Z"
}
```

### Input fields

#### `hashtags`

A list of hashtags to scrape. You can enter `booktok`, `#booktok`, or a TikTok tag URL.

#### `maxItemsPerHashtag`

Maximum public videos to save for each hashtag. Start small for first runs.

#### `sortMode`

TikTok public hashtag pages currently expose a top/trending feed. Recent sorting is not available in this first version.

#### `includeVideoDetails`

When enabled, the actor adds optional technical fields such as video width, height, and bitrate when TikTok returns them.

#### `proxyConfiguration`

TikTok is sensitive to automated browser traffic. The default uses Apify Residential proxy in the United States for better reliability.

### Tips for best results

- ✅ Use specific hashtags rather than extremely broad ones when possible.
- ✅ Keep first runs small while validating a workflow.
- ✅ Use several related hashtags to compare creators and captions.
- ✅ Retry later if TikTok temporarily serves a verification challenge.

### Integrations

Use the dataset output with:

- Google Sheets for campaign reporting
- Airtable for creator discovery workflows
- BI dashboards for engagement tracking
- CRM enrichment pipelines
- Apify webhooks for scheduled trend monitoring

### API usage — Node.js

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('fetch_cat/tiktok-hashtag-scraper').call({
  hashtags: ['booktok'],
  maxItemsPerHashtag: 20
});
console.log(run.defaultDatasetId);
```

### API usage — Python

```python
from apify_client import ApifyClient

client = ApifyClient('APIFY_TOKEN')
run = client.actor('fetch_cat/tiktok-hashtag-scraper').call(run_input={
    'hashtags': ['booktok'],
    'maxItemsPerHashtag': 20,
})
print(run['defaultDatasetId'])
```

### API usage — cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/fetch_cat~tiktok-hashtag-scraper/runs?token=APIFY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"hashtags":["booktok"],"maxItemsPerHashtag":20}'
```

### MCP integration

Use this actor from Apify MCP to collect hashtag video rows directly inside Claude Desktop, Claude Code, or another MCP client.

MCP server URL:

```text
https://mcp.apify.com/?tools=fetch_cat/tiktok-hashtag-scraper
```

Claude Code setup:

```bash
claude mcp add apify-tiktok-hashtags https://mcp.apify.com/?tools=fetch_cat/tiktok-hashtag-scraper
```

Claude Desktop JSON config:

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

Example prompts:

- “Collect 20 videos for #booktok and summarize the top captions.”
- “Find creators appearing in #skincare with high engagement.”
- “Compare #ai and #marketing TikTok videos.”

### Scheduling

You can schedule the actor daily or weekly to monitor how public hashtag results change over time.

### Data freshness

TikTok hashtag feeds change frequently. Each run collects the public results available at run time.

### Limits

The actor only collects public hashtag video data. It does not log in, collect private data, download videos, or bypass account-only features.

### Troubleshooting

#### Why did the run return no videos?

The hashtag may be empty, region-limited, or TikTok may have served a temporary verification challenge. Try again later or use the default residential proxy.

#### Why are counts different from the TikTok app?

TikTok updates engagement counts continuously and may personalize or localize public feeds.

### Legality

This actor is designed to collect publicly available information. You are responsible for using the data in compliance with applicable laws, TikTok terms, and privacy requirements.

### Related scrapers

- https://apify.com/fetch\_cat/tiktok-profile-scraper
- https://apify.com/fetch\_cat/tiktok-comments-scraper

### Support

If a run fails, open an Apify issue with the run URL, input, and expected result so we can investigate.

### Changelog

#### 0.1

Initial version for public TikTok hashtag videos.

### Notes

This actor focuses on clean normalized output for hashtag research and campaign reporting.

### FAQ

#### Can I scrape multiple hashtags?

Yes. Add multiple values to `hashtags`; the dataset includes the source hashtag for each row.

#### Can I get comments?

Not in this actor. Use a dedicated TikTok comments scraper for comment collection.

#### Can I download videos?

No. The output includes public video pages and metadata, not video files.

#### Can I scrape private videos?

No. Only public hashtag results are supported.

# Actor input Schema

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

Hashtags to scrape. Enter values with or without #, for example booktok or #fitness.

## `maxItemsPerHashtag` (type: `integer`):

Maximum number of public videos to save for each hashtag.

## `sortMode` (type: `string`):

TikTok public hashtag pages expose a top/trending feed. Recent sorting is not currently available without login.

## `includeVideoDetails` (type: `boolean`):

Add optional width, height, and bitrate fields when TikTok returns them.

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

TikTok usually requires residential proxy traffic. The default run uses Apify Residential proxy in the United States.

## Actor input object example

```json
{
  "hashtags": [
    "booktok"
  ],
  "maxItemsPerHashtag": 20,
  "sortMode": "top",
  "includeVideoDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `overview` (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": [
        "booktok"
    ],
    "maxItemsPerHashtag": 20,
    "sortMode": "top",
    "includeVideoDetails": false,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("fetch_cat/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 = {
    "hashtags": ["booktok"],
    "maxItemsPerHashtag": 20,
    "sortMode": "top",
    "includeVideoDetails": False,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("fetch_cat/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 '{
  "hashtags": [
    "booktok"
  ],
  "maxItemsPerHashtag": 20,
  "sortMode": "top",
  "includeVideoDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call fetch_cat/tiktok-hashtag-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "TikTok Hashtag Scraper",
        "description": "Scrape public TikTok hashtag videos, captions, creators, and engagement metrics for trend research and influencer discovery.",
        "version": "0.1",
        "x-build-id": "ZEe9JEveet6f1i4gD"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/fetch_cat~tiktok-hashtag-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-fetch_cat-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/fetch_cat~tiktok-hashtag-scraper/runs": {
            "post": {
                "operationId": "runs-sync-fetch_cat-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/fetch_cat~tiktok-hashtag-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-fetch_cat-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": [
                    "hashtags"
                ],
                "properties": {
                    "hashtags": {
                        "title": "TikTok hashtags",
                        "minItems": 1,
                        "type": "array",
                        "description": "Hashtags to scrape. Enter values with or without #, for example booktok or #fitness.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxItemsPerHashtag": {
                        "title": "Maximum videos per hashtag",
                        "minimum": 1,
                        "maximum": 500,
                        "type": "integer",
                        "description": "Maximum number of public videos to save for each hashtag.",
                        "default": 20
                    },
                    "sortMode": {
                        "title": "Sort mode",
                        "enum": [
                            "top"
                        ],
                        "type": "string",
                        "description": "TikTok public hashtag pages expose a top/trending feed. Recent sorting is not currently available without login.",
                        "default": "top"
                    },
                    "includeVideoDetails": {
                        "title": "Include video technical details",
                        "type": "boolean",
                        "description": "Add optional width, height, and bitrate fields when TikTok returns them.",
                        "default": false
                    },
                    "proxyConfiguration": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "TikTok usually requires residential proxy traffic. The default run uses Apify Residential proxy in the United States.",
                        "default": {
                            "useApifyProxy": true,
                            "apifyProxyGroups": [
                                "RESIDENTIAL"
                            ],
                            "apifyProxyCountry": "US"
                        }
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```