POST /api/v1/tiktok/trending/hashtags — 1 credit per request
Get the hashtags trending on TikTok right now in a country, over the last 7 or 30 days, with every category merged into one list by default, or just one category. Each one comes with its rank, how many videos and views it got, its popularity per day and its top creators.
Endpoint
Section titled “Endpoint”| Method | Path | Returns |
|---|---|---|
| POST | /api/v1/tiktok/trending/hashtags |
The trending hashtags for a country and period, every category merged or one category |
Request & Response
Section titled “Request & Response”Query parameters
Section titled “Query parameters”Send these in the URL query string. A request body is ignored. Every parameter is optional.
| Name | Type | Required | Description |
|---|---|---|---|
country |
string | No | A two-letter country code, any case. Default US. Supported: AE, AR, AU, BR, CA, CO, DE, EG, ES, FR, GB, ID, IL, IT, JP, KR, MX, MY, PH, SA, SG, TH, TR, TW, US, VN, ZA. Anything else is a 400 |
period |
integer | No | 7 (the default) or 30, in days. Anything else is a 400 |
category |
string | No | One of the category names or ids below. Case and punctuation are ignored (Beauty & Personal Care and beauty-personal-care are the same). A category is a single ranking of three hashtags. Leave it out to get every category merged. Not together with an explicit by_category=true |
by_category |
boolean | No | Default true when you send no category: every category’s ranking merged into one list of about 45 hashtags, for 1 credit. false returns the single all-categories ranking of three hashtags. Sending true together with category is a 400 |
One ranking holds three hashtags
Section titled “One ranking holds three hashtags”TikTok publishes only the top three per ranking to a logged-out reader. Without a category you get the merged list by default: the ranking of all categories and each of the 15 categories below, about 45 hashtags, each appearing once. Three hashtags is what you get with a category or with by_category=false.
Categories
Section titled “Categories”Apparel & Accessories, Baby, Kids & Maternity, Beauty & Personal Care, Education, Food & Beverage, Games, Health, Home Improvement, Household Products, News & Entertainment, Pets, Sports & Outdoor, Tech & Electronics, Travel, Vehicle & Transportation.
The country is a real filter: the ranking is the one TikTok publishes for that country.
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
success |
boolean | Always true on a 200 |
credits_charged |
integer | Credits this request cost; 0 for a ranking your key already paid for |
credits_remaining |
integer | Your balance after this request |
country |
string | The country the ranking is for |
period |
integer | Days the ranking covers |
category |
object | id and name. Present only when you asked for a category |
cached_at |
string | UTC time of the cached answer. Present only on a cached answer |
by_category |
boolean | true when the answer is the merged list (the default without a category). Absent otherwise |
hashtags |
array | Most popular first. In the merged list, about 45, ordered by views, then posts, then name. A single ranking (a category, or by_category=false) has at most three |
hashtags[].rank |
integer | 1 is the most popular. In the merged list it is the place in this answer’s own order (most views first), not a TikTok rank. Use rankings for TikTok’s own places |
hashtags[].hashtag_id |
string | TikTok’s id for the hashtag |
hashtags[].name |
string | The hashtag without the leading # |
hashtags[].posts |
integer | Videos that used it in the period, when reported. Absent is not zero |
hashtags[].views |
integer | Views of those videos in the period, when reported. Absent is not zero |
hashtags[].industries |
array | The categories TikTok files the hashtag under. Can be empty |
hashtags[].popularity_curve |
array | One point per day: timestamp (Unix seconds, UTC) and value, scaled so the hashtag’s own peak in the period is 100. Can be empty |
hashtags[].rankings |
array | Only in the merged list: each ranking the hashtag is in, with rank (TikTok’s place there) and category (id and name, absent for the ranking of all categories) |
hashtags[].top_creators |
array | Best first: rank, handle, nickname, followers (when reported), country. Can be empty |
The request waits for the lookup to finish, up to 45 seconds, so allow at least 30 seconds on your client. A request with no category makes 16 lookups, about 11 seconds when nothing is cached, and can take most of that time; if it has not finished you get a 503 and can resubmit. Only a 200 is ever charged. An empty ranking is a 404 and costs nothing.
Asking again for a ranking your key already paid for is free for 1 hour. The merged list is cached on its own, so a merged request and a single-ranking one (category or by_category=false) are charged separately. If any of the 16 lookups is refused, you get an uncharged 403 or 503, never a partial list.
curl -X POST "https://api.megomi.my.id/api/v1/tiktok/trending/hashtags?country=ID&period=30&category=Games" \ -H "x-api-key: YOUR_API_KEY"const params = new URLSearchParams({ country: "ID", period: "30", category: "Games",});const res = await fetch(`https://api.megomi.my.id/api/v1/tiktok/trending/hashtags?${params}`, { method: "POST", headers: { "x-api-key": process.env.MEGOMI_API_KEY },});const data = await res.json();import requests
res = requests.post( "https://api.megomi.my.id/api/v1/tiktok/trending/hashtags", params={"country": "ID", "period": 30, "category": "Games"}, headers={"x-api-key": "YOUR_API_KEY"},)print(res.json())<?php$query = http_build_query(["country" => "ID", "period" => 30, "category" => "Games"]);$ch = curl_init("https://api.megomi.my.id/api/v1/tiktok/trending/hashtags?" . $query);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);echo curl_exec($ch);q := url.Values{}q.Set("country", "ID")q.Set("period", "30")q.Set("category", "Games")req, _ := http.NewRequest("POST", "https://api.megomi.my.id/api/v1/tiktok/trending/hashtags?"+q.Encode(), nil)req.Header.Set("x-api-key", "YOUR_API_KEY")resp, _ := http.DefaultClient.Do(req){ "success": true, "credits_charged": 1, "credits_remaining": 999, "country": "US", "period": 7, "by_category": true, "hashtags": [ { "rank": 1, "hashtag_id": "1700000000000009", "name": "speedrunnight", "posts": 84213, "views": 500000000, "industries": [ { "id": "25000000000", "name": "Games" } ], "popularity_curve": [ { "timestamp": 1791504000, "value": 0 }, { "timestamp": 1791590400, "value": 56.47 }, { "timestamp": 1791676800, "value": 70.75 }, { "timestamp": 1791763200, "value": 80.71 }, { "timestamp": 1791849600, "value": 100 } ], "top_creators": [ { "rank": 1, "handle": "example_creator_4", "nickname": "Example Creator 4", "followers": 14665, "country": "US" }, { "rank": 2, "handle": "example_creator_5", "nickname": "Example Creator 5", "followers": 13276, "country": "US" }, { "rank": 3, "handle": "example_creator_6", "nickname": "Example Creator 6", "followers": 81505, "country": "US" } ], "rankings": [ { "category": { "id": "25000000000", "name": "Games" }, "rank": 3 } ] }, { "rank": 2, "hashtag_id": "1700000000000001", "name": "spacewalklive", "posts": 31666, "views": 235689495, "industries": [], "popularity_curve": [ { "timestamp": 1791331200, "value": 0 }, { "timestamp": 1791417600, "value": 58.18 }, { "timestamp": 1791504000, "value": 93.71 }, { "timestamp": 1791590400, "value": 100 }, { "timestamp": 1791676800, "value": 66.4 }, { "timestamp": 1791763200, "value": 47.09 }, { "timestamp": 1791849600, "value": 31.26 } ], "top_creators": [ { "rank": 1, "handle": "example_creator_1", "nickname": "Example Creator 1", "followers": 197744, "country": "US" }, { "rank": 2, "handle": "example_creator_2", "nickname": "Example Creator 2", "followers": 2873, "country": "US" }, { "rank": 3, "handle": "example_creator_3", "nickname": "Example Creator 3", "followers": 1547, "country": "US" } ], "rankings": [ { "rank": 1 }, { "category": { "id": "25000000000", "name": "Games" }, "rank": 2 } ] }, { "rank": 3, "hashtag_id": "1700000000000002", "name": "launchdaycountdown", "posts": 43514, "views": 131319765, "industries": [], "popularity_curve": [ { "timestamp": 1791504000, "value": 0 }, { "timestamp": 1791590400, "value": 56.47 }, { "timestamp": 1791676800, "value": 70.75 }, { "timestamp": 1791763200, "value": 80.71 }, { "timestamp": 1791849600, "value": 100 } ], "top_creators": [ { "rank": 1, "handle": "example_creator_4", "nickname": "Example Creator 4", "followers": 14665, "country": "US" }, { "rank": 2, "handle": "example_creator_5", "nickname": "Example Creator 5", "followers": 13276, "country": "US" }, { "rank": 3, "handle": "example_creator_6", "nickname": "Example Creator 6", "followers": 81505, "country": "US" } ], "rankings": [ { "rank": 2 } ] }, { "rank": 4, "hashtag_id": "1700000000000003", "name": "moonphasewatch", "posts": 107634, "views": 21689515, "industries": [ { "id": "25000000000", "name": "Games" } ], "popularity_curve": [ { "timestamp": 1791331200, "value": 0 }, { "timestamp": 1791417600, "value": 0.96 }, { "timestamp": 1791504000, "value": 97.95 }, { "timestamp": 1791590400, "value": 100 }, { "timestamp": 1791676800, "value": 58.49 }, { "timestamp": 1791763200, "value": 54.01 }, { "timestamp": 1791849600, "value": 62.61 } ], "top_creators": [ { "rank": 1, "handle": "example_creator_7", "nickname": "Example Creator 7", "followers": 16124, "country": "US" }, { "rank": 2, "handle": "example_creator_8", "nickname": "Example Creator 8", "followers": 361792, "country": "US" }, { "rank": 3, "handle": "example_creator_9", "nickname": "Example Creator 9", "followers": 236999, "country": "US" } ], "rankings": [ { "rank": 3 }, { "category": { "id": "25000000000", "name": "Games" }, "rank": 1 } ] } ], "status_code": 0, "status_msg": ""}{ "status": 400, "title": "Bad Request", "detail": "period must be 7 or 30" }{ "status": 401, "title": "Unauthorized", "detail": "invalid API key" }{ "status": 402, "title": "Payment Required", "detail": "insufficient credit balance", "required": 1, "balance": 0}{ "status": 404, "title": "Not Found", "detail": "TikTok's Creative Center has no trending hashtags for this country, period and category; you were not charged. This answer is cached for about 15 minutes", "requestId": "req_9f1kQ3zP7mLxA2dR", "finishReason": "no-trending-hashtags"}Other responses
Section titled “Other responses”| Status | When | finishReason |
What to do |
|---|---|---|---|
404 |
There are no trending hashtags for this country, period and category (for the merged list, in none of the 16 rankings) | no-trending-hashtags |
Not charged. Checked again after about 15 minutes |
403 |
TikTok refused the lookup | login-wall and others |
Not charged. Retry after the Retry-After header |
503 |
No answer in time, or the lookup failed | varies | Not charged. Resubmit after Retry-After; it is free if the work finished |