Skip to content

Structured TikTok data: send usernames. Cursor-paginated, 1 credit per successful call.

GET · POST1 credit / successful callCursor-paginated
GEThttps://api.scrapier.io/api/v2/tiktok-profile-region/Open in Playground

Call GET /api/v2/tiktok-profile-region/ with usernames. The results are in data.profile; send data.next_cursor back as cursor to get the next page. 3 optional parameters refine the call (see Parameters).

Terminal window
curl -G "https://api.scrapier.io/api/v2/tiktok-profile-region/" \
-H "X-API-Key: YOUR_API_KEY" \
--data-urlencode "usernames=shakira" \
--max-time 210
NameTypeRequiredDefaultDescription
X-API-Key headerstringyes—Your API key from the dashboard.
usernamesstringyese.g. shakiraTikTok handle or profile URL: "shakira", "@shakira" or "https://www.tiktok.com/@shakira". One profile per call (single lookup, next_cursor is always null).
cursorstringno—Pagination cursor returned in the previous response's next_cursor. Pass it back unchanged to fetch the next page. When next_cursor is null, you have reached the last page.
videos_to_checkintegerno5Newest public videos whose locationCreated vote for the region (0-13, default 5). 0 = author card only, region null.
include_videosbooleannotrueAttach recent_videos (the per-video evidence behind the region vote).
Advanced
NameTypeDefaultDescription
use_proxybooleantrueRoute the request through Scrapier's residential proxy pool. Default: true. Leave as is unless support tells you otherwise.
raw_databooleanfalseWhen true, the response carries the full raw upstream payload(s) the scraper received (GraphQL / JSON API bodies, HTML, embedded JSON-LD -- exactly as the platform returned them) under raw_responses, in place of the formatted items. When false (default) you get the formatted output. Pagination (cursor / next_cursor) works the same in both modes.
{
"success": true,
"data": {
"usernames": "stoolpresidente",
"profile": {
"input_username": "stoolpresidente",
"username": "stoolpresidente",
"profile_url": "https://www.tiktok.com/@stoolpresidente",
"status": "ok",
"region": "US",
"country_name": "United States",
"region_source": "video_location_created",
"region_confidence": 1,
"region_votes": {
"US": 5
},
"region_evidence": {
"videos_checked": 5,
"videos_with_region": 5,
"latest_video_region": "US",
"unanimous": true
},
"author": {
"id": "stoolpresidente",
"user_id": "6659752019493208069",
"sec_uid": "MS4wLjABAAAAINC_ElRR-l1RCcnEjOZhNO-9wOzAMf-YHXqRY8vvG9bEhMRa6iu23TaE3JPZYXBD",
"short_id": null,
"username": "stoolpresidente",
"display_name": "Dave Portnoy",
"avatar_url": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310178711609032710~tplv-tiktokx-cropcenter:1080:1080.jpeg",
"avatar_medium_url": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310178711609032710~tplv-tiktokx-cropcenter:720:720.jpeg",
"avatar_thumb_url": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310178711609032710~tplv-tiktokx-cropcenter:100:100.jpeg",
"bio": "El Presidente/Barstool Sports Founder.",
"bio_link": "https://www.barstoolsports.com/bios/el-presidente",
"bio_link_risk": 0,
"verified": true,
"private": false,
"secret": false,
"is_organization": false,
"is_commerce_user": false,
"is_tt_seller": false,
"is_ad_virtual": false,
"is_embed_banned": false,
"followers": 4781641,
"following": 97,
"friends_count": 64,
"posts_count": 2534,
"likes_count": 230647760,
"digg_count": 0,
"url": "https://www.tiktok.com/@stoolpresidente",
"location": "US",
"language": "en",
"created_at": "2019-02-19T16:42:27Z",
"username_modified_at": null,
"display_name_modified_at": null,
"live_room_id": null,
"settings": {
"comment": 0,
"duet": 0,
"stitch": 0,
"download": 0,
"following_visibility": 1,
"profile_embed_permission": 1,
"open_favorite": false
},
"profile_tabs": {
"music": false,
"questions": false,
"playlists": true
},
"share_meta": {
"title": "Dave Portnoy on TikTok",
"desc": "@stoolpresidente 4.8m Followers, 97 Following, 230.6m Likes - Watch awesome short videos created by Dave Portnoy"
}
},
"computed": {
"engagement_rate": 0.3993,
"language": "en",
"content_category": "Pizza Reviews",
"estimated_reach": 188960,
"avg_plays": 188960,
"avg_likes": 16755,
"avg_comments": 238,
"avg_shares": 2100,
"posting_frequency_days": 1.09,
"top_hashtags": []
},
"recent_videos": [
{
"id": "7687061086398418190",
"url": "https://www.tiktok.com/@stoolpresidente/video/7687061086398418190",
"description": "I can declare this $36 slice gimmick pizza ",
"created_at": "2026-09-19T02:03:20Z",
"location_created": "US",
"duration": 59,
"cover_url": "https://p19-common-sign.tiktokcdn.com/tos-useast5-p-0068-tx/ocABAWttcB1IfBLA9CBvoEzCJV7IiaiwAQBC54~tplv-tiktokx-origin.image",
"hashtags": [],
"playlist": {
"id": "7090570072548461358",
"name": "Pizza Reviews",
"video_count": 651
},
"music": {
"id": "7687061166736100109",
"title": "original sound",
"author": "Dave Portnoy",
"duration": 59
},
"stats": {
"plays": 21100,
"likes": 2035,
"comments": 39,
"shares": 8,
"saves": 17
},
"search_indexable": true,
"aigc_label_type": null
}
],
"warnings": [],
"duration_ms": 2270,
"scraped_at": "2026-09-19T00:00:00.000Z"
},
"next_cursor": null
}
}

Sample from the live catalog; arrays trimmed to 3 items. Results are in data.profile.

FieldTypeExampleDescription
usernamesstringstoolpresidente—
profileobject{…}The results.
next_cursornullnullPass back as cursor for the next page. null on the last page.
profile.input_usernamestringstoolpresidente—
profile.usernamestringstoolpresidente—
profile.profile_urlstringhttps://www.tiktok.com/@stoolpresidente—
profile.statusstringok—
profile.regionstringUS—
profile.country_namestringUnited States—
profile.region_sourcestringvideo_location_created—
profile.region_confidenceinteger1—
profile.region_votesobject{…}—
profile.region_evidenceobject{…}—
profile.authorobject{…}—
profile.computedobject{…}—
profile.recent_videosarray[1 item]—
profile.warningsarray[]—
profile.duration_msinteger2270—
profile.scraped_atstring2026-09-19T00:00:00.000Z—

Pass data.next_cursor back as cursor until it is null. Required inputs are ignored once a cursor is sent. Each page is one billed call. More in Pagination.

const url = "https://api.scrapier.io/api/v2/tiktok-profile-region/";
let params = { usernames: "shakira" };
const items = [];
for (let page = 0; page < 10; page++) { // each page is one billed call
const res = await fetch(`${url}?${new URLSearchParams(params)}`, {
headers: { "X-API-Key": "YOUR_API_KEY" },
signal: AbortSignal.timeout(210_000),
});
const body = await res.json();
if (!res.ok) throw new Error(body.error ?? body.detail ?? `HTTP ${res.status}`);
const data = body.data;
items.push(data.profile);
if (!data.next_cursor) break; // null = last page
params = { cursor: data.next_cursor };
}

Failed calls are free. Branch on the HTTP status and read the message from error (or detail). Full details in Errors.

StatusMeaningRetry?Charged?
400Bad or missing input.No — fix the paramsNo
401 / 403Missing, invalid or revoked API key.No — fix the keyNo
402Out of credits (body has balance).No — top upNo
404Unknown endpoint slug.No — check the slugNo
429 / 503Busy or throttled.Yes — after Retry-AfterNo
5xxTarget site or upstream failure, or timeout.Yes — with backoffNo
  • Nothing special: send the inputs, read the result.
  • TikTok Ad Library Leads — Structured TikTok data: every input is optional. Single lookup, 3 credits per successful call.
  • TikTok Ad Library — Structured TikTok data: send urls. Cursor-paginated, 1 credit per successful call.
  • TikTok Ads Top — Structured TikTok data: every input is optional. Cursor-paginated, 1 credit per successful call.
  • TikTok Collection Videos — Structured TikTok data: send urls. Cursor-paginated, 1 credit per successful call.