# TikTok Hashtag Trends Scraper (`crawlerbros/tiktok-hashtag-trends-scraper`) Actor Track trending TikTok hashtags from the Creative Center. Returns rank, post count, video views, popularity curve, and top creators for each trending hashtag. - **URL**: https://apify.com/crawlerbros/tiktok-hashtag-trends-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Social media, Automation, SEO tools - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/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 Trends Scraper Track trending TikTok hashtags from the Creative Center at ads.tiktok.com/business/creativecenter/hashtag. Returns ranked hashtags with post count, total video views, and a time-series popularity curve showing trend momentum. Supports any country available in TikTok Creative Center. Note: the public unauthenticated endpoint caps results at 3 hashtags per request. ### What this actor does - Fetches trending hashtags from TikTok's Creative Center trends API - Returns rank position, post count, video views, and a popularity curve per hashtag - Filters by country (any ISO 2-letter code supported by Creative Center) and time period - Records `observedCountry` and `observedPeriod` on each row for dataset provenance - Exits cleanly with a log message if TikTok restricts access from the current IP — no crash or error rows - Empty fields are omitted ### Output per hashtag - `hashtagId` — TikTok's internal hashtag identifier - `hashtagName` — hashtag text without the `#` symbol - `publishCnt` — number of videos published using this hashtag in the observed period - `rankIndex` — rank position in the trending list (1 = most trending) - `popularityCurve` — array of `{ time, value }` data points showing trend momentum over the period - `vv` — total video views on content using this hashtag - `observedCountry` — country code used for this query - `observedPeriod` — time period in days used for this query - `scrapedAt` — ISO 8601 timestamp of collection ### Input | Field | Type | Default | Description | |---|---|---|---| | `country` | string | `"US"` | ISO 2-letter country code (e.g. `US`, `GB`, `JP`, `KR`, `BR`). Country-specific results depend on a matching proxy IP being available. | | `period` | string | `"7"` | Trend observation window: `"7"` (recent spikes), `"30"` (sustained trends), or `"180"` (long-term). | | `maxRanks` | integer | `3` | Maximum number of trending hashtags to return. TikTok's public unauthenticated endpoint caps this at 3. | #### Example: Top 3 trending hashtags in the US this week ```json { "country": "US", "period": "7", "maxRanks": 3 } ```` #### Example: 30-day trends in the UK ```json { "country": "GB", "period": "30", "maxRanks": 3 } ``` #### Example: Long-term trends in Japan ```json { "country": "JP", "period": "180", "maxRanks": 3 } ``` #### Example: Weekly trends in Brazil ```json { "country": "BR", "period": "7", "maxRanks": 3 } ``` ### Use cases - **Content strategy** — identify the hashtags driving the most views right now in your target market and incorporate them into upcoming posts - **Campaign timing** — monitor the popularity curve to catch hashtags at the start of their upward trend before they peak - **Market research** — compare trending hashtags across countries to understand regional audience interests and cultural moments - **Influencer briefing** — provide creators with a weekly top-3 list of trending hashtags in their niche or geography - **Competitor benchmarking** — track whether your brand or category hashtags appear in the trending list over time ### FAQ **Q: Why does the actor only return 3 hashtags?**\ A: TikTok's public Creative Center endpoint caps unauthenticated requests at 3 hashtags per query. This is a platform-level limit, not an actor limitation. **Q: What countries are supported?**\ A: Any country code recognized by TikTok Creative Center, including US, GB, JP, KR, BR, DE, FR, ID, TH, VN, PH, AU, CA, MX, and many more. **Q: How often should I run this actor?**\ A: For daily trend monitoring, run once per day. TikTok updates Creative Center trends on a daily cycle. **Q: How do I monitor multiple countries?**\ A: Run the actor once per country. Each run is fast (only 3 results), so monitoring 10–20 countries daily is practical. **Q: What is the `popularityCurve` field?**\ A: An array of `{ time, value }` data points that shows how the hashtag's popularity score changed over the selected period. Use it to determine whether a hashtag is rising, peaked, or declining. **Q: What is `publishCnt` vs `vv`?**\ A: `publishCnt` is the number of new videos posted with the hashtag during the period. `vv` is the total view count accumulated on those videos. A hashtag with low `publishCnt` but high `vv` indicates high per-video virality. **Q: What happens if no data is returned?**\ A: TikTok occasionally restricts Creative Center API access from certain datacenter IP ranges. When this occurs, the actor logs a clear message and exits cleanly without pushing error rows. ### Related TikTok Scrapers Build a complete TikTok data pipeline with our full suite: | Scraper | URL | |---|---| | TikTok Post Scraper | https://apify.com/crawlerbros/tiktok-post-scraper | | TikTok Profile Scraper | https://apify.com/crawlerbros/tiktok-profile-scraper | | TikTok Comments Scraper | https://apify.com/crawlerbros/tiktok-comments-scraper | | TikTok Search Scraper | https://apify.com/crawlerbros/tiktok-search-scraper | | TikTok Hashtag Scraper | https://apify.com/crawlerbros/tiktok-hashtag-scraper | | TikTok Music Scraper | https://apify.com/crawlerbros/tiktok-music-scraper | | TikTok Transcript Scraper | https://apify.com/crawlerbros/tiktok-transcript-scraper | | TikTok Followers Scraper | https://apify.com/crawlerbros/tiktok-followers-scraper | | TikTok Mention Scraper | https://apify.com/crawlerbros/tiktok-mention-scraper | | TikTok Profile Mention Scraper | https://apify.com/crawlerbros/tiktok-profile-mention-scraper | | TikTok Playlist Scraper | https://apify.com/crawlerbros/tiktok-playlist-scraper | | TikTok Explore Scraper | https://apify.com/crawlerbros/tiktok-explore-scraper | | TikTok For You Scraper | https://apify.com/crawlerbros/tiktok-for-you-scraper | | TikTok Downloader | https://apify.com/crawlerbros/tiktok-downloader-api | | TikTok Ads Library Scraper | https://apify.com/crawlerbros/tiktok-ads-library-scraper-pro | | TikTok Top Ads Scraper | https://apify.com/crawlerbros/tiktok-top-ads-scraper | | TikTok LIVE Scraper | https://apify.com/crawlerbros/tiktok-live-scraper | # Actor input Schema ## `country` (type: `string`): ISO 2-letter country code for the target market (e.g. US, GB, JP, KR, BR). Country-specific results depend on a residential proxy IP in that country being available — otherwise the server defaults to the IP's detected region. ## `period` (type: `string`): Trend observation window. 7 days shows recent viral spikes; 30 days shows sustained trends. ## `maxRanks` (type: `integer`): Maximum number of trending hashtags to return. TikTok's public endpoint caps unauthenticated requests at 3 items. ## Actor input object example ```json { "country": "US", "period": "7", "maxRanks": 3 } ``` # Actor output Schema ## `data` (type: `string`): Dataset containing one record per trending hashtag with rank, post count, video views, popularity curve and top creator 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "country": "US", "period": "7", "maxRanks": 3 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/tiktok-hashtag-trends-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "country": "US", "period": "7", "maxRanks": 3, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/tiktok-hashtag-trends-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 '{ "country": "US", "period": "7", "maxRanks": 3 }' | apify call crawlerbros/tiktok-hashtag-trends-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/tiktok-hashtag-trends-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Hashtag Trends Scraper", "description": "Track trending TikTok hashtags from the Creative Center. Returns rank, post count, video views, popularity curve, and top creators for each trending hashtag.", "version": "1.0", "x-build-id": "E3pF8C5uMuCUtzUEM" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~tiktok-hashtag-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-tiktok-hashtag-trends-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/crawlerbros~tiktok-hashtag-trends-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-tiktok-hashtag-trends-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/crawlerbros~tiktok-hashtag-trends-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-tiktok-hashtag-trends-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", "properties": { "country": { "title": "Country", "type": "string", "description": "ISO 2-letter country code for the target market (e.g. US, GB, JP, KR, BR). Country-specific results depend on a residential proxy IP in that country being available — otherwise the server defaults to the IP's detected region.", "default": "US" }, "period": { "title": "Time Period (Days)", "enum": [ "7", "30", "180" ], "type": "string", "description": "Trend observation window. 7 days shows recent viral spikes; 30 days shows sustained trends.", "default": "7" }, "maxRanks": { "title": "Maximum Hashtags", "minimum": 1, "maximum": 3, "type": "integer", "description": "Maximum number of trending hashtags to return. TikTok's public endpoint caps unauthenticated requests at 3 items.", "default": 3 } } }, "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 } } } } } } } } } } ```