POST /api/v1/tiktok/audience — 15 credits per request
Send a TikTok handle and get an estimate of the creator’s audience: a language mix plus a best-effort country breakdown. TikTok does not publish audience geography, so this is an estimate built from public signals and not a figure TikTok reports.
Endpoint
Section titled “Endpoint”| Method | Path | Returns |
|---|---|---|
| POST | /api/v1/tiktok/audience |
An estimate of one creator’s audience |
Request & Response
Section titled “Request & Response”Request
Section titled “Request”| Name | Where | Type | Required | Description |
|---|---|---|---|---|
handle |
body | string (max 2048) | Yes | The creator’s handle: letters, digits, . and _, up to 64 characters, with an optional leading @, case ignored. A profile URL (https://www.tiktok.com/@nasa) or a profile share link also works. A URL that names the profile only by its numeric id is a 400 |
- Send a JSON body with
Content-Type: application/json. There are no query parameters. - The body is required, and a field other than
handleis a400.
This is an estimate
Section titled “This is an estimate”TikTok does not publish a creator’s audience geography. This endpoint estimates it from public signals. Read audienceLanguages as the main result and audienceLocations as a rough signal.
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
requestId |
string | Opaque ID for this request (req_…). Quote it when reporting a problem |
handle |
string | The handle you asked for, lowercased, without @ |
status |
string | "success" on every 200 |
cached |
boolean | true if answered from a recent fetch. Free if your key already paid for this profile |
result |
object | The estimate, see below |
The result object
Section titled “The result object”| Field | Type | Description |
|---|---|---|
handle |
string | The creator this estimate describes |
handle |
string | The creator whose audience this describes |
audienceLanguages |
array | The estimated language mix, largest first: { code, share }. code is a short lowercase language code (en, id, zh-hant). A language whose share rounds to 0 is left out |
audienceLocations |
array | A best-effort country estimate (may be empty), largest first: { country, countryCode, share }. Only languages spoken overwhelmingly in one country are mapped, such as Indonesian, Thai, Japanese, Korean or Malay. A country whose share rounds to 0 is left out |
unclassifiedShare |
number | Share of the audience whose language could not be determined |
unattributedLocationShare |
number | Share whose language cannot be tied to a single country, such as English. A high value means the country estimate is weak for this creator |
asOf |
string | When the estimate was made (RFC 3339), when known |
note |
string | A plain-language caveat about what this estimate is |
Reading the estimate
Section titled “Reading the estimate”audienceLanguagesis the main result and is meaningful for every creator.audienceLocationsis reliable for creators whose audience speaks a distinctive, single-country language (for example Indonesian → Indonesia). For a creator whose audience is mostly English-speaking, or uses another widely spoken language, most of the audience lands inunattributedLocationShareandaudienceLocationswill be small or empty. That is by design: the endpoint does not invent a country split.- Treat the shares as a directional signal, not a census of followers.
- Shares are fractions between 0 and 1, rounded to 2 decimals, and those that round to 0 are left out, so the groups add up to about 1, not exactly 1.
- An account with too little public activity to estimate from is a
404withfinishReasoninsufficient-data.
Caching and cost
Section titled “Caching and cost”A fresh answer is shared across keys for 10 minutes (1 hour for a profile that does not exist), per handle. Only a 200 is charged, and this is one of the more expensive endpoints, so guard how often you call it. Asking again for a profile your key already paid for is free while it is cached, and resubmitting after a 503 never charges twice. A 403, 404, 429 and 503 are never charged. A fresh answer takes longer than the other TikTok lookups, usually well inside the 45 second wait. A cached one is immediate.
Errors
Section titled “Errors”| Status | When | What to do |
|---|---|---|
400 |
No body, no handle, a handle that is not valid, a field other than handle, or a URL that names the profile only by its numeric id |
Fix the request |
401 |
No API key, or an unknown one | Check your key |
402 |
Your balance cannot cover this plus your unfinished lookups, or the key’s own credit limit | Buy credit |
403 |
An estimate for this account is unavailable right now (source-unavailable) |
Not charged. Retry in a few minutes, not in a loop |
404 |
TikTok reports no such account (user-not-found), or the account has too little public activity to estimate from (insufficient-data) |
Not charged. Cached for 1 hour |
429 |
Rate limit, or too many unfinished lookups | Slow down |
503 |
No estimate in time (temporarily-unavailable) |
Not charged and not cached. Resubmit shortly. It is free if the work finished |
curl -X POST https://api.megomi.my.id/api/v1/tiktok/audience \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"handle": "nasa"}'const res = await fetch("https://api.megomi.my.id/api/v1/tiktok/audience", { method: "POST", headers: { "x-api-key": process.env.MEGOMI_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ handle: "nasa" }), signal: AbortSignal.timeout(60_000),});const data = await res.json();import requests
res = requests.post( "https://api.megomi.my.id/api/v1/tiktok/audience", json={"handle": "nasa"}, headers={"x-api-key": "YOUR_API_KEY"}, timeout=60,)print(res.json())<?php$ch = curl_init("https://api.megomi.my.id/api/v1/tiktok/audience");curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY", "Content-Type: application/json"]);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["handle" => "nasa"]));curl_setopt($ch, CURLOPT_TIMEOUT, 60);curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);echo curl_exec($ch);payload := strings.NewReader(`{"handle": "nasa"}`)req, _ := http.NewRequest("POST", "https://api.megomi.my.id/api/v1/tiktok/audience", payload)req.Header.Set("x-api-key", "YOUR_API_KEY")req.Header.Set("Content-Type", "application/json")client := &http.Client{Timeout: 60 * time.Second}resp, _ := client.Do(req){ "requestId": "req_9f1kQ3zP7mLxA2dR", "handle": "nasa", "status": "success", "cached": false, "result": { "handle": "nasa", "audienceLanguages": [ { "code": "en", "share": 0.63 }, { "code": "id", "share": 0.18 }, { "code": "th", "share": 0.07 }, { "code": "ja", "share": 0.04 } ], "audienceLocations": [ { "country": "Indonesia", "countryCode": "ID", "share": 0.18 }, { "country": "Thailand", "countryCode": "TH", "share": 0.07 }, { "country": "Japan", "countryCode": "JP", "share": 0.04 } ], "unclassifiedShare": 0.08, "unattributedLocationShare": 0.63, "asOf": "2026-11-13T10:00:00Z", "note": "An estimate built from public signals, not a figure TikTok reports. Treat audienceLocations as a rough signal: widely-spoken languages (such as English) are not attributed to any country." }}{ "status": 400, "title": "Bad Request", "detail": "handle is required: send the creator's handle or profile URL in the JSON body"}{ "status": 403, "title": "Forbidden", "detail": "an estimate for this account is unavailable right now; you were not charged", "requestId": "req_5mPq1XwK8jVcT4nR", "handle": "nasa", "finishReason": "source-unavailable"}{ "status": 404, "title": "Not Found", "detail": "TikTok reports no such account; you were not charged. This answer is cached for an hour", "requestId": "req_5mPq1XwK8jVcT4nR", "finishReason": "user-not-found"}{ "status": 503, "title": "Service Unavailable", "detail": "no estimate within 45s; you were not charged. The lookup is still running: submitting the same request again shortly may return it from cache, and is never charged twice", "requestId": "req_1qLr6PxV8nWtE3sJ", "finishReason": "temporarily-unavailable"}