Read a TikTok profile as JSON

What you send

Send handle or id. handle is the username, with or without @. username is an alias. id is the numeric TikTok user id. Aliases are user_id, secUid and sec_uid. The reference is explicit: a secUid cannot be looked up. Use the handle or the numeric id.

The recorded request uses a handle.

1curl -G "https://api.socialscrape.dev/v1/tiktok/profile" \2  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \3  --data-urlencode "handle=khaby.lame"

1import os2import requests34params = {5    "handle": "khaby.lame",6}7res = requests.get(8    "https://api.socialscrape.dev/v1/tiktok/profile",9    headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},10    params=params,11)12body = res.json()1314if body["ok"]:15    print(body["data"])16else:17    print(body["error"]["code"], body["error"]["message"])

1const url = new URL("https://api.socialscrape.dev/v1/tiktok/profile");2url.search = new URLSearchParams({3  "handle": "khaby.lame"4}).toString();5const res = await fetch(url, {6  headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },7});8const body = await res.json();910if (body.ok) {11  console.log(body.data);12} else {13  console.error(body.error.code, body.error.message);14}

Check ok before reading data. On failure, branch on error.code and error.retryable, not on the message text. invalid_params and not_found are not retryable. rate_limited is.

max_age_days from 0 to 30 serves a cached copy for 0 credits. This endpoint keeps results 30 days. trim drops nulls and extra. raw adds the platform object. See caching.

What the profile contains

data is one profile, not a list. object is profile and platform is tiktok.

Identity and text: id, handle, name, headline, url, kind, bio, avatar_url, banner_url. verified and is_private are booleans. external_url and links are the bio link. location, category and created_at are present on the model and null when TikTok does not show them.

stats

holds followers, following, posts, likes and views. On a TikTok profile the follower, following, post and like counts are the totals. views is null when the profile does not carry a view total.

extra

on the recorded profile includes comment_setting, download_setting, duet_setting, stitch_setting, following_visible, friends, is_commerce_user, is_organization, is_tiktok_seller, language and sec_uid. Those are platform details, not a second copy of the counts. A field TikTok omits is null.

There is no list of followers. stats.followers is a count. If a search result sent you a handle, this is the call that turns it into counts. User search is GET /v1/tiktok/search/users.

The latest videos

GET /v1/tiktok/profile/videos returns the newest videos of an account, read from TikTok's embed page. One page is about 10 videos: pinned videos first, then newest first.

Pass handle. The reference says a numeric id cannot be looked up on this route, and sort=popular is refused. include_pinned set to false drops pinned videos that can be told from the page order.

1curl -G "https://api.socialscrape.dev/v1/tiktok/profile/videos" \2  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \3  --data-urlencode "handle=khaby.lame"

1import os2import requests34params = {5    "handle": "khaby.lame",6}7res = requests.get(8    "https://api.socialscrape.dev/v1/tiktok/profile/videos",9    headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},10    params=params,11)12body = res.json()1314if body["ok"]:15    print(body["data"])16else:17    print(body["error"]["code"], body["error"]["message"])

1const url = new URL("https://api.socialscrape.dev/v1/tiktok/profile/videos");2url.search = new URLSearchParams({3  "handle": "khaby.lame"4}).toString();5const res = await fetch(url, {6  headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },7});8const body = await res.json();910if (body.ok) {11  console.log(body.data);12} else {13  console.error(body.error.code, body.error.message);14}

data.items

are posts. Each one has id, url, text (the caption), hashtags, published_at, media, song, author and stats. The play count is stats.views. TikTok rounds it to two significant digits, and extra.views_rounded says so. The date is taken from the video id: extra.published_at_from_id. is_pinned is true for a pinned video that can be told from the order. The reference says it never over-reports.

has_more

is false and there is no cursor. That is because more videos cannot be fetched, not because the account has only ten videos. parent is the account.

Likes, comments, shares and duration are not on the embed page, so stats.likes, stats.comments, stats.shares and duration_seconds stay null. If you need likes on one video, that is a different call, GET /v1/tiktok/video, with the video URL or id. Do not read a null like count as zero.

A private account answers private on the video list. The profile call's errors are invalid_params and not_found.