Audience
https://scraper.riken.me/v1/tiktok/user/audienceTry it
Paste your key under Authorization and send a live request to https://scraper.riken.me. The key stays in this browser tab only (session storage, cleared when the tab closes) and is sent nowhere else. A live request spends credits like any other.
The countries of an account's followers, estimated from a sample: we read the newest 720 followers and place up to 150 by the country their latest video was posted from. Estimates, subject to change.
Usually 35 to 40 seconds; up to 5 minutes. Set your client timeout to at least 6 minutes.
Charged only when 30 or more followers are placed. 1 to 29 placed:
200, free, X-Audience-Confidence: low. None placed: 200,
audienceLocations: [], free. Private account: 200, free,
{"account_private": true, "handle"}. Some free answers are kept per
account (24 h; private 6 h) and served again with X-Audience-Cached.
Limits: 2 audience requests in flight per key (a third is
429 rate_limited, Retry-After: 30); past 100 free answers in 10
minutes, audience requests from the key are refused before they run.
Coming in beta. Answers 503 route_not_priced until priced.
Headers
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
x-api-key | string | one of the auth headers | Your API key. If both headers are sent, `x-api-key` wins. | sk_... |
Authorization | string | one of the auth headers | `Authorization: Bearer <key>`, the same key. | Bearer sk_... |
Idempotency-Key | string | no | Any string up to 255 characters. Makes a retry safe for 24 hours; bound to this API key and the request's parameters. | profile-dagestantrainingcamp-2026-11-01 |
Query parameters
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
handle | string | yes | The TikTok handle; a leading `@` is removed. The only parameter, as on ScrapeCreators. | karlaakat |
Status codes
| Status | Charged | Meaning |
|---|---|---|
| 200 | Depends | The country breakdown (charged at 30+ placed, else free), or the private answer (free). |
| 400 | Free | A parameter is missing, malformed, or one we cannot honour yet. Free. |
| 401 | Free | Missing, unknown or revoked key. Free. |
| 402 | Free | The key cannot cover this request. needed_credits is the price. Free. |
| 404 | Free | The account does not exist. Free; counts toward the free-answer limit. |
| 409 | Free | A request with this Idempotency-Key and parameters is still running. Free; retry after Retry-After (1 s). |
| 429 | Free | Over capacity (over_capacity), or the key's audience limits (rate_limited). Free. |
| 500 | Free | Our fault. Free; retry and quote X-Request-Id. |
| 502 | Free | TikTok's answer failed or could not be read (including accounts TikTok withholds from logged-out views). Free. |
| 503 | Free | The route has no price yet, so it does not serve. Free. |
| 504 | Free | No answer within the time limit (180 s; audience 300 s). Free. |
The country breakdown (charged at 30+ placed, else free), or the private answer (free).
application/json- response
success*unknowncredits_charged*CreditsAn amount in credits, as an exact JSON decimal (1, 0.002), never a rounded float.
0 <= valuecredits_remaining*CreditsRemainingWhat the key can still spend after this request.
audienceLocations*array<>The whole country breakdown, count descending (ties by country code). Empty when no follower could be placed.
Example request
# A call can be held open up to 180 s (audience: 300 s). Set a client timeout above that.curl -X GET 'https://scraper.riken.me/v1/tiktok/user/audience?handle=karlaakat' \ -H 'Idempotency-Key: profile-dagestantrainingcamp-2026-11-01'The example file is rendered with the generic 1-credit envelope; a charged audience answer carries credits_charged 20.
{ "audienceLocations": [ { "count": 115, "country": "United States", "countryCode": "US", "percentage": "70.55%" }, { "count": 19, "country": "Mexico", "countryCode": "MX", "percentage": "11.66%" }, { "count": 3, "country": "Chile", "countryCode": "CL", "percentage": "1.84%" } ], "credits_charged": 1, "credits_remaining": 999, "success": true}