TikTok live status API
Whether the user is live now, with the room's details when they are.
- Cost
- 1 credit
- Cached repeats
- Nonealways fetched live
- Failed requests
- 0 credits
- Status
- Betashape may still gain fields
You send handle.
Request
Send your key in the x-api-key header.
curl -G "https://api.socialscrape.io/v1/tiktok/profile/live" \
-H "x-api-key: $SOCIALSCRAPE_API_KEY" \
--data-urlencode 'handle=khaby.lame'import os
import requests
params = {
"handle": "khaby.lame",
}
res = requests.get(
"https://api.socialscrape.io/v1/tiktok/profile/live",
headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},
params=params,
timeout=60,
)
body = res.json()
if body["ok"]:
print(body["data"])
else:
print(body["error"]["code"], body["error"]["message"])const url = new URL("https://api.socialscrape.io/v1/tiktok/profile/live");
url.search = new URLSearchParams({
handle: "khaby.lame",
}).toString();
const res = await fetch(url, {
headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },
});
const body = await res.json();
if (body.ok) {
console.log(body.data);
} else {
console.error(body.error.code, body.error.message);
}{
"nodes": [
{
"name": "SocialScrape Is a TikTok user live",
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4.2,
"position": [
0,
0
],
"parameters": {
"method": "GET",
"url": "https://api.socialscrape.io/v1/tiktok/profile/live",
"sendQuery": true,
"queryParameters": {
"parameters": [
{
"name": "handle",
"value": "khaby.lame"
}
]
},
"sendHeaders": true,
"headerParameters": {
"parameters": [
{
"name": "x-api-key",
"value": "={{ $env.SOCIALSCRAPE_API_KEY }}"
}
]
}
}
}
],
"connections": {}
}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
handle | string | yes | Username, with or without the leading @. Also accepted as username. |
Every request also accepts trim, raw and max_age_days.
Response
Sample from a recorded response, shortened. Values are public data, not yours.
{
"ok": true,
"credits_charged": 1,
"credits_remaining": 4999,
"cached": false,
"cached_at": null,
"request_id": "req_2ed53439a70e8af86fc87135",
"data": {
"object": "live_stream",
"platform": "tiktok",
"is_live": false,
"id": null,
"url": "https://www.tiktok.com/@khaby.lame/live",
"author": {
"id": "127905465618821121",
"handle": "khaby.lame",
"name": "Khabane lame",
"url": "https://www.tiktok.com/@khaby.lame",
"avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:100:100.jpeg?dr=9640&refresh_token...",
"verified": true
},
"title": null,
"viewer_count": null,
"like_count": null,
"started_at": null,
"cover_url": null,
"extra": null
},
"cursor": null,
"has_more": null
}Fields
One LiveStream in data.
A field the platform does not give is null, never made up. Extra platform details are in extra.
| Field | Type | Always | Notes |
|---|---|---|---|
object | "live_stream" | ||
platform | Platform | yes | |
is_live | boolean | yes | |
id | string or null | room / stream id | |
url | string or null | ||
author | Author or null | ||
title | string or null | ||
viewer_count | integer or null | ||
like_count | integer or null | ||
started_at | string (ISO 8601 date-time) or null | ||
cover_url | string or null | ||
extra | object or null |
Full field list in the reference for this endpoint and the data models. Errors are listed under Errors.
Questions
Which errors can it return?
invalid_params (do not retry), not_found (do not retry). Account and platform errors from the errors list can also happen. A failure always costs 0 credits.
Is there an SDK call for it?
The preview Python client has client.tiktok.profile_live(...) and the TypeScript client client.tiktok.profileLive(). Both return the same envelope as the HTTP API. The packages are not published yet; plain HTTP works today in any language.
Can an AI agent call it?
Yes. The MCP server reaches every built endpoint, with the same prices.