Skip to content

TikTok Audience

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.

Method Path Returns
POST /api/v1/tiktok/audience An estimate of one creator’s audience
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 handle is a 400.

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.

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
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
  • audienceLanguages is the main result and is meaningful for every creator.
  • audienceLocations is 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 in unattributedLocationShare and audienceLocations will 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 404 with finishReason insufficient-data.

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.

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
Terminal window
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"}'
{
"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."
}
}