# TikTok Hashtag Search Scraper (`maximedupre/tiktok-hashtag-search-scraper`) Actor

Find TikTok hashtag ideas from keywords, hashtags, or tag URLs. Export public hashtag metrics such as views, user count, flags, rank, and source query.

- **URL**: https://apify.com/maximedupre/tiktok-hashtag-search-scraper.md
- **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community)
- **Categories:** Social media, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.45 / 1,000 hashtags

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 search scraper for keyword research

TikTok Hashtag Search Scraper finds public [TikTok](https://www.tiktok.com/) hashtags from keywords, hashtags, or TikTok tag URLs. Add a seed term such as `dance`, `fitness`, or `#skincare`, and the Actor returns ranked hashtag rows with public TikTok metrics such as view count, user count, commerce flags, source query, hashtag URL, and scrape time.

Use this TikTok hashtag search scraper when you need structured hashtag ideas for TikTok SEO, campaign planning, creator research, trend checks, brand monitoring, or social media reporting. Instead of typing the same searches into TikTok by hand, you get a clean Apify dataset you can download as JSON, CSV, Excel, XML, RSS, or HTML, or use through the Apify API, schedules, webhooks, and integrations.

For a small first run, keep the prefilled `dance` keyword and lower **Total hashtag results** to `10` if you only want to inspect the output shape. The Actor works with public TikTok hashtag search data and does not require your TikTok login, cookies, or a TikTok API key.

### ✅ What this Actor does

- Searches TikTok hashtag data from one or more keywords.
- Accepts plain keywords, `#hashtags`, and `https://www.tiktok.com/tag/...` URLs.
- Saves one dataset item per accepted hashtag result.
- Preserves the source input, input position, and result rank.
- Returns hashtag IDs, names, titles, TikTok hashtag URLs, descriptions, and scrape timestamps.
- Adds public metrics such as view count, user count, and video count when TikTok returns them.
- Adds public flags such as commerce, challenge, promoted, PGC show, strong music, and type when available.
- Stops at your per-input and total result limits so run size is predictable.
- Runs without a user-provided TikTok account, cookie, or API key.

### 📊 Data you get

Each dataset row represents one TikTok hashtag result. Fields can include:

- `query` and `sourceQuery`: the keyword, hashtag, or tag URL you submitted.
- `queryIndex` and `rank`: where the input appeared and where the hashtag appeared in the returned results.
- `sourceType`: whether the row came from a keyword, hashtag, or hashtag URL input.
- `hashtagId`, `hashtagName`, and `hashtagTitle`: TikTok hashtag identifiers and display text.
- `hashtagUrl` and `challengeUrl`: direct links to the TikTok hashtag page.
- `description`: public hashtag description when TikTok exposes one.
- `viewCount`, `userCount`, and `videoCount`: public TikTok metrics when available.
- `isCommerce`, `isChallenge`, `isPromoted`, `isPgcShow`, `isStrongMusic`, and `type`: public classification fields when available.
- `coverUrl`, `profileImageUrl`, and `scrapedAt`: media and collection metadata when available.

TikTok may return `null` for fields it does not expose for a specific hashtag. The Actor does not create placeholder rows for inputs that return no usable hashtag metrics.

### 🚀 How to run it

1. Add one or more TikTok keywords, hashtags, or tag URLs.
2. Set **Hashtags per input** to cap how many hashtag results each input can save.
3. Set **Total hashtag results** to cap the full run.
4. Start the Actor and open the dataset when the run finishes.
5. Export the dataset or connect it to your API, scheduler, webhook, or integration workflow.

Good first inputs:

```json
{
  "queries": ["dance", "#fitness", "https://www.tiktok.com/tag/food"],
  "maxHashtagsPerQuery": 30,
  "maxTotalResults": 100
}
````

### 🧾 Output example

```json
{
  "query": "dance",
  "queryIndex": 1,
  "rank": 1,
  "sourceType": "keyword",
  "sourceQuery": "dance",
  "hashtagId": "dance",
  "hashtagName": "dance",
  "hashtagTitle": "dance",
  "hashtagUrl": "https://www.tiktok.com/tag/dance",
  "challengeUrl": "https://www.tiktok.com/tag/dance",
  "description": null,
  "viewCount": 1723017979660,
  "videoCount": null,
  "userCount": 147365531,
  "isCommerce": false,
  "isChallenge": null,
  "isPromoted": null,
  "isPgcShow": false,
  "isStrongMusic": null,
  "type": 2,
  "coverUrl": null,
  "profileImageUrl": null,
  "scrapedAt": "2026-05-29T22:55:13.111Z"
}
```

### 💡 Use cases

- Build TikTok SEO keyword lists from real hashtag suggestions.
- Compare hashtag view counts and user participation before planning content.
- Find related hashtag variants for campaign briefs and creator instructions.
- Monitor branded hashtag families and adjacent trend terms.
- Feed hashtag data into dashboards, spreadsheets, or social listening workflows.
- Create repeatable hashtag exports for clients, reports, or internal research.

### 💳 Pricing

This Actor uses pay-per-event pricing. You are charged for each accepted hashtag saved to the dataset. The pricing event is **Hashtag** at `$0.00445` per hashtag row.

Use **Total hashtag results** to control the maximum number of charged hashtag rows in a run. Inputs that return no usable hashtag metrics do not save dataset rows.

### ⚠️ Limits and caveats

- The Actor returns public TikTok hashtag search data, not videos, comments, profiles, or private account data.
- TikTok can return different result counts for different keywords. A keyword may return fewer rows than your limit.
- Some metrics or flags can be `null` when TikTok does not expose that field for a hashtag.
- Hashtag and URL inputs are treated as exact hashtag targets, while plain keyword inputs can return related hashtag ideas.
- This Actor is not affiliated with TikTok.

### ❓ FAQ

#### Do I need a TikTok account?

No. You do not need to provide a TikTok login, cookies, or a TikTok API key.

#### Can I search more than one keyword?

Yes. Add multiple values to **Keywords, hashtags, or tag URLs**. Each input is checked separately and the run stops at your total result limit.

#### Does this scrape TikTok videos?

No. This Actor is focused on hashtag search metrics. Use a TikTok video, transcript, or profile Actor if you need video-level data.

#### Why did I get fewer rows than my limit?

TikTok may return fewer public hashtag results for a specific keyword or exact hashtag. The Actor saves accepted hashtag rows only.

### 📝 Changelog

- 0.0: Initial release.

### 🆘 Support

For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~tiktok-hashtag-search-scraper/issues) and I'll fix or implement it in less than 24h 🫡

### 🔗 Other actors

- [TikTok Keywords Discovery Tool ↗](https://apify.com/maximedupre/tiktok-keywords-discovery-tool) - collect TikTok autocomplete keyword suggestions for content planning.
- [TikTok Profile Mention Scraper ↗](https://apify.com/maximedupre/tiktok-profile-mention-scraper) - find public TikTok videos that mention selected profiles.
- [TikTok Transcript Scraper ↗](https://apify.com/maximedupre/tiktok-transcript-scraper) - extract transcripts and subtitle text from public TikTok videos.
- [TikTok Video Downloader ↗](https://apify.com/maximedupre/tiktok-video-downloader) - download media files from public TikTok video URLs.
- [TikTok Story Viewer ↗](https://apify.com/maximedupre/tiktok-story-viewer) - export active public stories from TikTok profiles.

**Made with ❤️ by Maxime Dupré**

# Actor input Schema

## `queries` (type: `array`):

Add plain keywords like `dance challenge`, hashtags like `#fitness`, or TikTok tag URLs like `https://www.tiktok.com/tag/food`. Each input is checked separately.

## `maxHashtagsPerQuery` (type: `integer`):

Maximum hashtag rows to save for each keyword, hashtag, or URL. Use `1` for a tiny validation run or keep `30` for a normal hashtag search export.

## `maxTotalResults` (type: `integer`):

Maximum hashtag rows to save across the whole run. This is the easiest way to control cost and dataset size.

## Actor input object example

```json
{
  "queries": [
    "dance",
    "#fitness",
    "https://www.tiktok.com/tag/food"
  ],
  "maxHashtagsPerQuery": 30,
  "maxTotalResults": 100
}
```

# Actor output Schema

## `datasetItems` (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 = {
    "queries": [
        "dance",
        "#fitness",
        "https://www.tiktok.com/tag/food"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("maximedupre/tiktok-hashtag-search-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 = { "queries": [
        "dance",
        "#fitness",
        "https://www.tiktok.com/tag/food",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("maximedupre/tiktok-hashtag-search-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 '{
  "queries": [
    "dance",
    "#fitness",
    "https://www.tiktok.com/tag/food"
  ]
}' |
apify call maximedupre/tiktok-hashtag-search-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "TikTok Hashtag Search Scraper",
        "description": "Find TikTok hashtag ideas from keywords, hashtags, or tag URLs. Export public hashtag metrics such as views, user count, flags, rank, and source query.",
        "version": "0.0",
        "x-build-id": "DAZdfv6p2uQfpim0Y"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/maximedupre~tiktok-hashtag-search-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-maximedupre-tiktok-hashtag-search-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/maximedupre~tiktok-hashtag-search-scraper/runs": {
            "post": {
                "operationId": "runs-sync-maximedupre-tiktok-hashtag-search-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/maximedupre~tiktok-hashtag-search-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-maximedupre-tiktok-hashtag-search-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": [
                    "queries"
                ],
                "properties": {
                    "queries": {
                        "title": "TikTok targets",
                        "minItems": 1,
                        "maxItems": 500,
                        "type": "array",
                        "description": "Add plain keywords like `dance challenge`, hashtags like `#fitness`, or TikTok tag URLs like `https://www.tiktok.com/tag/food`. Each input is checked separately.",
                        "items": {
                            "type": "string",
                            "minLength": 1
                        }
                    },
                    "maxHashtagsPerQuery": {
                        "title": "Hashtags per input",
                        "minimum": 1,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "Maximum hashtag rows to save for each keyword, hashtag, or URL. Use `1` for a tiny validation run or keep `30` for a normal hashtag search export.",
                        "default": 30
                    },
                    "maxTotalResults": {
                        "title": "Total hashtag results",
                        "minimum": 1,
                        "maximum": 5000,
                        "type": "integer",
                        "description": "Maximum hashtag rows to save across the whole run. This is the easiest way to control cost and dataset size.",
                        "default": 100
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```