TikTok Profile Region API
The market TikTok assigns a creator's account. Read from TikTok's own region field: on the profile where TikTok publishes one, otherwise from the region stamped on the creator's recent posts. Never inferred from language, timezone or content. **Required:** Pass either handle or url. Calls cost 1 credit each. A cache hit is free, and a failed or empty response is never charged.
Try it
Prefilled with the request that produced the example below. No key yet? Get a free key.
Request
/v1/tiktok/profile/region| Parameter | Type | Required | Description |
|---|---|---|---|
| handle | string | no | Creator handle, e.g. @nasa |
| url | string | no | Profile URL, e.g. https://www.tiktok.com/@nasa |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
curl "$API/v1/tiktok/profile/region?handle=nike&cache_max_age=7d" \
-H "x-api-key: $KEY"const query = new URLSearchParams({
handle: 'nike',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/tiktok/profile/region?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/tiktok/profile/region",
params={
"handle": "nike",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Example response
Captured on , with raw removed and lists cut to two items. A live call returns current data.
{
"success": true,
"data": {
"platform": "tiktok",
"handle": "nike",
"userId": "208464585232822272",
"region": "US",
"source": "posts",
"agreement": [
{
"region": "US",
"count": 3
}
],
"fetchedAt": "2026-10-21T01:55:07.972Z"
},
"meta": {
"platform": "tiktok",
"endpoint": "tiktok.profileRegion",
"creditsCharged": 1,
"cached": false,
"cacheAgeSeconds": null,
"durationMs": 4764,
"requestId": "req_ha7qi15esizoj6qvkokh"
}
}Returns
Returns an object with platform, handle, userId, region, source, agreement, fetchedAt.
Fields
| Field | Type | Present | Description |
|---|---|---|---|
| platform | "tiktok" | always | |
| handle | string | always | |
| userId | string | always | |
| region | string | null | always | Two-letter market code as TikTok reports it. Never inferred. |
| source | profile | posts | null | always | Where the value came from, so a caller can weigh it. |
| agreement | object[] | always | From posts: how many sampled posts agreed. A traveller can carry several. |
| agreement[].region | string | always | |
| agreement[].count | number | always | |
| fetchedAt | string | always |
Cost and behaviour
| Credits | 1 per live request, 0 on a cache hit |
| Cacheable | yes: cache_max_age accepts a cached copy |
| Batchable | yes: usable as a target in POST /v1/jobs/batch |
| Subscribable | yes: as often as every 3600 seconds, firing a webhook only on a change |
Other TikTok endpoints
- /v1/tiktok/ad-library/ad One TikTok ad
- /v1/tiktok/ad-library/search Search the TikTok Ads Library
- /v1/tiktok/collection/videos Collection videos
- /v1/tiktok/comment-replies Replies to a comment
- /v1/tiktok/comments Comments on a video
- /v1/tiktok/creators/popular Popular creators
- /v1/tiktok/followers Accounts following a creator
- /v1/tiktok/following Accounts a creator follows