LIVE stream
curl --request GET \
--url https://api.scraperize.com/v1/tiktok/user/live \
--header 'x-api-key: <api-key>'import requests
url = "https://api.scraperize.com/v1/tiktok/user/live"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.scraperize.com/v1/tiktok/user/live', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.scraperize.com/v1/tiktok/user/live",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.scraperize.com/v1/tiktok/user/live"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.scraperize.com/v1/tiktok/user/live")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scraperize.com/v1/tiktok/user/live")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": {
"isLive": true,
"user": {
"id": "7228617106127094790",
"secUid": "MS4wLjABAAAAMGcjyEIH8K4TtQaDqwdsnBW8YViN51OijSuKZUXfzreVMAjaVR1Kjsz3PbzBs-o-",
"handle": "pepper_979",
"nickname": "PEPPER 🌶️ 🇻🇳🤪",
"bio": "Focus 🧘 and consistent 🫵no pain no gain 🦾in god I trust",
"avatarUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/a8fedb5d82169ba633dc52bbc6c0df04~tplv-tiktokx-cropcenter:1080:1080.webp?dr=14579&refresh_token=5b38f0b1&x-expires=1791381600&x-signature=joO1kIWg0cj6NSL%2F4fs5eYIpNlg%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=sg1",
"verified": false,
"isPrivate": false,
"followerCount": 51931,
"followingCount": 1063,
"profileUrl": "https://www.tiktok.com/@pepper_979",
"liveUrl": "https://www.tiktok.com/@pepper_979/live"
},
"live": {
"roomId": "7693190947967142674",
"streamId": "7693191100006648584",
"title": null,
"shareUrl": "https://m.tiktok.com/share/live/7693190947967142674/?language=en",
"coverUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/a8fedb5d82169ba633dc52bbc6c0df04~tplv-tiktokx-cropcenter:720:720.webp?dr=14579&refresh_token=2bb0dd73&x-expires=1791381600&x-signature=nCzwj8Ru%2BSOkobcWBAKh9zR%2FR3Y%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=my2",
"startedAt": "2026-10-05T14:30:40.000Z",
"viewerCount": 148,
"totalViewers": 818,
"newFollowers": 1,
"category": null,
"game": null,
"broadcastType": "camera",
"isCoHosting": false,
"battle": {
"id": "7693193300111002386",
"startedAt": "2026-10-05T14:39:34.000Z",
"durationSeconds": 301,
"isFinished": true,
"opponentUserId": "6550835996421210114",
"scores": [
{
"userId": "6550835996421210114",
"score": 3096,
"isHost": false
},
{
"userId": "7228617106127094790",
"score": 189,
"isHost": true
}
]
},
"topGifters": [
{
"userId": "6731150825269953538",
"secUid": "MS4wLjABAAAAFyQ7R9hdb9C2rSyxDOztOWtOHwadTeZ6X28kjdL8HpAWKk0NIS0GIQuWD-kx_9-h",
"handle": "minhon030399",
"nickname": "Mi NhOn🇨🇳•🇻🇳",
"avatarUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/2439730fad7a0dbfbe0642d7ba6c2354~tplv-tiktokx-cropcenter:1080:1080.webp?dr=14579&refresh_token=1ff1d3c8&x-expires=1791381600&x-signature=%2BhmIWVBbpR7fBfAL07pFhkG03S4%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=my2",
"followerCount": 10129,
"gifterLevel": 21,
"giftScore": 52
},
{
"userId": "7309836249065309185",
"secUid": "MS4wLjABAAAA_rsKms5hFCasYOLN1q2MaO9QlFJvBCE2JRpEL-8Vwh7ZdXQOVklifoqRFsjjT245",
"handle": "thuonglamminhoi9073",
"nickname": "꧁🌸 mình ơi 🌸꧂",
"avatarUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/ec4bfdd1de1813629ac7074aed19a79a~tplv-tiktokx-cropcenter:1080:1080.webp?dr=14579&refresh_token=edb19cd9&x-expires=1791381600&x-signature=uaQq7CnvytllIwViojhW5W6IAQs%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=my2",
"followerCount": 1399,
"gifterLevel": 20,
"giftScore": 2
},
{
"userId": "7333870882122875922",
"secUid": "MS4wLjABAAAAIC6uvGU0cXcJlMXVlei48yEk7PsFn0tSlSJla5UPI5w7tUKPVHN6BQPpwodGtLfv",
"handle": "khnh.linh70453",
"nickname": "Nga linh",
"avatarUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/76062d2de37ef9f4dcde423f36b051ef~tplv-tiktokx-cropcenter:1080:1080.webp?dr=14579&refresh_token=26fcb08b&x-expires=1791381600&x-signature=AFBf2DPTitVNfs%2FKJRvEiI%2BiwJc%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=my2",
"followerCount": 371,
"gifterLevel": 8,
"giftScore": 1
}
],
"ageRestricted": false,
"subscriberOnly": false,
"isPaidEvent": false,
"hasShop": false,
"shopProductCount": 0,
"chatEnabled": true,
"giftsEnabled": true,
"streams": [
{
"quality": "origin",
"name": "Original",
"codec": "h265",
"isAudioOnly": false,
"resolution": "1080x1920",
"width": 1080,
"height": 1920,
"bitrate": 3000000,
"flvUrl": "https://pull-flv-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584.flv?expire=1792421138&sign=f284dccf5dbf6416acd819bcbd7025b0",
"hlsUrl": "https://pull-hls-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584/index.m3u8?expire=1792421138&sign=e0b4ecfe2c9fdeefe9812ea28308947a",
"dashUrl": null,
"expiresAt": "2026-10-19T14:45:38.000Z"
},
{
"quality": "hd",
"name": "720p",
"codec": "h265",
"isAudioOnly": false,
"resolution": "720x1280",
"width": 720,
"height": 1280,
"bitrate": 1350000,
"flvUrl": "https://pull-flv-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584_hd5.flv?expire=1792421138&sign=db865332703a94e0c6bea858ce2a003b",
"hlsUrl": "https://pull-hls-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584_hd5/index.m3u8?expire=1792421138&sign=6f48b10b47fc311323859cb0378bd1aa",
"dashUrl": null,
"expiresAt": "2026-10-19T14:45:38.000Z"
},
{
"quality": "hd",
"name": "720p",
"codec": "h264",
"isAudioOnly": false,
"resolution": "720x1280",
"width": 720,
"height": 1280,
"bitrate": 1000000,
"flvUrl": "https://pull-flv-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584_hd.flv?expire=1792421138&sign=34df89a4aefc297245a436423250320b",
"hlsUrl": "https://pull-hls-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584_hd/index.m3u8?expire=1792421138&sign=0f9a6e5e0fa748bc56a572b6a7e2a6f8",
"dashUrl": null,
"expiresAt": "2026-10-19T14:45:38.000Z"
}
]
},
"lastLive": null,
"fetchedAt": "2026-10-05T14:45:39.366Z"
},
"meta": {
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
"creditsCharged": 1,
"creditsRemaining": 4999,
"cached": false
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "API key required — pass it in the `x-api-key` header.",
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f"
}
}{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "This request costs 1 credit, but your balance is 0. Top up to continue.",
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "The requested content was not found (it may not exist, be deleted, or be private).",
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f"
}
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
"details": [
{
"path": "url",
"message": "Required"
}
]
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded — max 100 requests per 60s. Retry in ~30s.",
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f"
}
}{
"error": {
"code": "UPSTREAM_BLOCKED",
"message": "The source is temporarily unavailable. Please try again shortly.",
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f"
}
}TikTok
LIVE stream
Returns whether a TikTok account is LIVE right now and, if it is, the stream: title, start time, viewers watching now, total viewers so far, new followers during the LIVE, category and game (for gaming streams), how it is broadcast (camera, screen share, streaming software or audio), co-hosting, the current battle (PK) with both scores and the opponent, the top gifters (with their gifter level and gift score), age-restriction, subscriber-only, paid-event and shop flags, and the stream URLs — every quality TikTok offers (e.g. Original, 720p60, 720p, 540p, 360p, in H.264 and H.265, plus audio only) as FLV and HLS links with resolution, bitrate and expiry. Stream URLs play without extra headers and expire after a while. The account itself comes with its ids, nickname, bio, avatar, verified / private flags and follower counts. When the account is not LIVE, isLive is false, live is null and lastLive describes its most recent LIVE as TikTok reports it (title, start and end, duration, total viewers), or null if there is none.
GET
/
v1
/
tiktok
/
user
/
live
LIVE stream
curl --request GET \
--url https://api.scraperize.com/v1/tiktok/user/live \
--header 'x-api-key: <api-key>'import requests
url = "https://api.scraperize.com/v1/tiktok/user/live"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.scraperize.com/v1/tiktok/user/live', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.scraperize.com/v1/tiktok/user/live",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.scraperize.com/v1/tiktok/user/live"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.scraperize.com/v1/tiktok/user/live")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.scraperize.com/v1/tiktok/user/live")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"data": {
"isLive": true,
"user": {
"id": "7228617106127094790",
"secUid": "MS4wLjABAAAAMGcjyEIH8K4TtQaDqwdsnBW8YViN51OijSuKZUXfzreVMAjaVR1Kjsz3PbzBs-o-",
"handle": "pepper_979",
"nickname": "PEPPER 🌶️ 🇻🇳🤪",
"bio": "Focus 🧘 and consistent 🫵no pain no gain 🦾in god I trust",
"avatarUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/a8fedb5d82169ba633dc52bbc6c0df04~tplv-tiktokx-cropcenter:1080:1080.webp?dr=14579&refresh_token=5b38f0b1&x-expires=1791381600&x-signature=joO1kIWg0cj6NSL%2F4fs5eYIpNlg%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=sg1",
"verified": false,
"isPrivate": false,
"followerCount": 51931,
"followingCount": 1063,
"profileUrl": "https://www.tiktok.com/@pepper_979",
"liveUrl": "https://www.tiktok.com/@pepper_979/live"
},
"live": {
"roomId": "7693190947967142674",
"streamId": "7693191100006648584",
"title": null,
"shareUrl": "https://m.tiktok.com/share/live/7693190947967142674/?language=en",
"coverUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/a8fedb5d82169ba633dc52bbc6c0df04~tplv-tiktokx-cropcenter:720:720.webp?dr=14579&refresh_token=2bb0dd73&x-expires=1791381600&x-signature=nCzwj8Ru%2BSOkobcWBAKh9zR%2FR3Y%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=my2",
"startedAt": "2026-10-05T14:30:40.000Z",
"viewerCount": 148,
"totalViewers": 818,
"newFollowers": 1,
"category": null,
"game": null,
"broadcastType": "camera",
"isCoHosting": false,
"battle": {
"id": "7693193300111002386",
"startedAt": "2026-10-05T14:39:34.000Z",
"durationSeconds": 301,
"isFinished": true,
"opponentUserId": "6550835996421210114",
"scores": [
{
"userId": "6550835996421210114",
"score": 3096,
"isHost": false
},
{
"userId": "7228617106127094790",
"score": 189,
"isHost": true
}
]
},
"topGifters": [
{
"userId": "6731150825269953538",
"secUid": "MS4wLjABAAAAFyQ7R9hdb9C2rSyxDOztOWtOHwadTeZ6X28kjdL8HpAWKk0NIS0GIQuWD-kx_9-h",
"handle": "minhon030399",
"nickname": "Mi NhOn🇨🇳•🇻🇳",
"avatarUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/2439730fad7a0dbfbe0642d7ba6c2354~tplv-tiktokx-cropcenter:1080:1080.webp?dr=14579&refresh_token=1ff1d3c8&x-expires=1791381600&x-signature=%2BhmIWVBbpR7fBfAL07pFhkG03S4%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=my2",
"followerCount": 10129,
"gifterLevel": 21,
"giftScore": 52
},
{
"userId": "7309836249065309185",
"secUid": "MS4wLjABAAAA_rsKms5hFCasYOLN1q2MaO9QlFJvBCE2JRpEL-8Vwh7ZdXQOVklifoqRFsjjT245",
"handle": "thuonglamminhoi9073",
"nickname": "꧁🌸 mình ơi 🌸꧂",
"avatarUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/ec4bfdd1de1813629ac7074aed19a79a~tplv-tiktokx-cropcenter:1080:1080.webp?dr=14579&refresh_token=edb19cd9&x-expires=1791381600&x-signature=uaQq7CnvytllIwViojhW5W6IAQs%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=my2",
"followerCount": 1399,
"gifterLevel": 20,
"giftScore": 2
},
{
"userId": "7333870882122875922",
"secUid": "MS4wLjABAAAAIC6uvGU0cXcJlMXVlei48yEk7PsFn0tSlSJla5UPI5w7tUKPVHN6BQPpwodGtLfv",
"handle": "khnh.linh70453",
"nickname": "Nga linh",
"avatarUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/76062d2de37ef9f4dcde423f36b051ef~tplv-tiktokx-cropcenter:1080:1080.webp?dr=14579&refresh_token=26fcb08b&x-expires=1791381600&x-signature=AFBf2DPTitVNfs%2FKJRvEiI%2BiwJc%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=my2",
"followerCount": 371,
"gifterLevel": 8,
"giftScore": 1
}
],
"ageRestricted": false,
"subscriberOnly": false,
"isPaidEvent": false,
"hasShop": false,
"shopProductCount": 0,
"chatEnabled": true,
"giftsEnabled": true,
"streams": [
{
"quality": "origin",
"name": "Original",
"codec": "h265",
"isAudioOnly": false,
"resolution": "1080x1920",
"width": 1080,
"height": 1920,
"bitrate": 3000000,
"flvUrl": "https://pull-flv-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584.flv?expire=1792421138&sign=f284dccf5dbf6416acd819bcbd7025b0",
"hlsUrl": "https://pull-hls-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584/index.m3u8?expire=1792421138&sign=e0b4ecfe2c9fdeefe9812ea28308947a",
"dashUrl": null,
"expiresAt": "2026-10-19T14:45:38.000Z"
},
{
"quality": "hd",
"name": "720p",
"codec": "h265",
"isAudioOnly": false,
"resolution": "720x1280",
"width": 720,
"height": 1280,
"bitrate": 1350000,
"flvUrl": "https://pull-flv-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584_hd5.flv?expire=1792421138&sign=db865332703a94e0c6bea858ce2a003b",
"hlsUrl": "https://pull-hls-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584_hd5/index.m3u8?expire=1792421138&sign=6f48b10b47fc311323859cb0378bd1aa",
"dashUrl": null,
"expiresAt": "2026-10-19T14:45:38.000Z"
},
{
"quality": "hd",
"name": "720p",
"codec": "h264",
"isAudioOnly": false,
"resolution": "720x1280",
"width": 720,
"height": 1280,
"bitrate": 1000000,
"flvUrl": "https://pull-flv-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584_hd.flv?expire=1792421138&sign=34df89a4aefc297245a436423250320b",
"hlsUrl": "https://pull-hls-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584_hd/index.m3u8?expire=1792421138&sign=0f9a6e5e0fa748bc56a572b6a7e2a6f8",
"dashUrl": null,
"expiresAt": "2026-10-19T14:45:38.000Z"
}
]
},
"lastLive": null,
"fetchedAt": "2026-10-05T14:45:39.366Z"
},
"meta": {
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
"creditsCharged": 1,
"creditsRemaining": 4999,
"cached": false
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "API key required — pass it in the `x-api-key` header.",
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f"
}
}{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "This request costs 1 credit, but your balance is 0. Top up to continue.",
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "The requested content was not found (it may not exist, be deleted, or be private).",
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f"
}
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
"details": [
{
"path": "url",
"message": "Required"
}
]
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded — max 100 requests per 60s. Retry in ~30s.",
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f"
}
}{
"error": {
"code": "UPSTREAM_BLOCKED",
"message": "The source is temporarily unavailable. Please try again shortly.",
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f"
}
}Cost: 1 credit per successful request. Errors and cache hits (
cache_max_age) are free.Copy for AI assistant
Copy for AI assistant
Paste this into ChatGPT, Claude or your coding assistant to generate working code for this endpoint (use the copy button).
Prompt
I want to make an API call to /v1/tiktok/user/live. Here are the details:
Endpoint: GET https://api.scraperize.com/v1/tiktok/user/live
Description: Returns whether a TikTok account is LIVE right now and, if it is, the stream: title, start time, viewers watching now, total viewers so far, new followers during the LIVE, category and game (for gaming streams), how it is broadcast (camera, screen share, streaming software or audio), co-hosting, the current battle (PK) with both scores and the opponent, the top gifters (with their gifter level and gift score), age-restriction, subscriber-only, paid-event and shop flags, and the stream URLs — every quality TikTok offers (e.g. Original, 720p60, 720p, 540p, 360p, in H.264 and H.265, plus audio only) as FLV and HLS links with resolution, bitrate and expiry. Stream URLs play without extra headers and expire after a while. The account itself comes with its ids, nickname, bio, avatar, verified / private flags and follower counts. When the account is not LIVE, `isLive` is false, `live` is null and `lastLive` describes its most recent LIVE as TikTok reports it (title, start and end, duration, total viewers), or null if there is none.
Required Headers:
- x-api-key: Your API key
Parameters:
- handle (string) [required]: The TikTok username (with or without a leading @, or a tiktok.com/@username URL).
- cache_max_age (select): Optional. Return a cached result if one this age or newer exists — served for **0 credits** with `meta.cached=true` and `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and refreshes the cache. Omit to always scrape fresh.
Example Response:
{
"data": {
"isLive": true,
"user": {
"id": "7228617106127094790",
"secUid": "MS4wLjABAAAAMGcjyEIH8K4TtQaDqwdsnBW8YViN51OijSuKZUXfzreVMAjaVR1Kjsz3PbzBs-o-",
"handle": "pepper_979",
"nickname": "PEPPER 🌶️ 🇻🇳🤪",
"bio": "Focus 🧘 and consistent 🫵no pain no gain 🦾in god I trust",
"avatarUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/a8fedb5d82169ba633dc52bbc6c0df04~tplv-tiktokx-cropcenter:1080:1080.webp?dr=14579&refresh_token=5b38f0b1…",
"verified": false,
"isPrivate": false,
"followerCount": 51931,
"followingCount": 1063,
"profileUrl": "https://www.tiktok.com/@pepper_979",
"liveUrl": "https://www.tiktok.com/@pepper_979/live"
},
"live": {
"roomId": "7693190947967142674",
"streamId": "7693191100006648584",
"title": null,
"shareUrl": "https://m.tiktok.com/share/live/7693190947967142674/?language=en",
"coverUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/a8fedb5d82169ba633dc52bbc6c0df04~tplv-tiktokx-cropcenter:720:720.webp?dr=14579&refresh_token=2bb0dd73&x…",
"startedAt": "2026-10-05T14:30:40.000Z",
"viewerCount": 148,
"totalViewers": 818,
"newFollowers": 1,
"category": null,
"game": null,
"broadcastType": "camera",
"isCoHosting": false,
"battle": {
"id": "7693193300111002386",
"startedAt": "2026-10-05T14:39:34.000Z",
"durationSeconds": 301,
"isFinished": true,
"opponentUserId": "6550835996421210114",
"scores": [
{
"userId": "6550835996421210114",
"score": 3096,
"isHost": false
}
]
},
"topGifters": [
{
"userId": "6731150825269953538",
"secUid": "MS4wLjABAAAAFyQ7R9hdb9C2rSyxDOztOWtOHwadTeZ6X28kjdL8HpAWKk0NIS0GIQuWD-kx_9-h",
"handle": "minhon030399",
"nickname": "Mi NhOn🇨🇳•🇻🇳",
"avatarUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/2439730fad7a0dbfbe0642d7ba6c2354~tplv-tiktokx-cropcenter:1080:1080.webp?dr=14579&refresh_token=1ff1d3c8…",
"followerCount": 10129,
"gifterLevel": 21,
"giftScore": 52
}
],
"ageRestricted": false,
"subscriberOnly": false,
"isPaidEvent": false,
"hasShop": false,
"shopProductCount": 0,
"chatEnabled": true,
"giftsEnabled": true,
"streams": [
{
"quality": "origin",
"name": "Original",
"codec": "h265",
"isAudioOnly": false,
"resolution": "1080x1920",
"width": 1080,
"height": 1920,
"bitrate": 3000000,
"flvUrl": "https://pull-flv-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584.flv?expire=1792421138&sign=f284dccf5dbf6416acd819bcbd7025b0",
"hlsUrl": "https://pull-hls-l1-sg01.tiktokcdn.com/stage/stream-7693191100006648584/index.m3u8?expire=1792421138&sign=e0b4ecfe2c9fdeefe9812ea28308947a",
"dashUrl": null,
"expiresAt": "2026-10-19T14:45:38.000Z"
}
]
},
"lastLive": null,
"fetchedAt": "2026-10-05T14:45:39.366Z"
},
"meta": {
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
"creditsCharged": 1,
"creditsRemaining": 4999,
"cached": false
}
}
Please help me write code in my preferred programming language to make this API call and handle the response appropriately. Include error handling and best practices.
Authorizations
Your API key. Send it in the x-api-key header (or Authorization: Bearer <key>). Create and manage keys from your dashboard.
Query Parameters
The TikTok username (with or without a leading @, or a tiktok.com/@username URL).
Optional. Return a cached result if one this age or newer exists — served for 0 credits with meta.cached=true and meta.cachedAt. Otherwise a fresh scrape runs (1 credit) and refreshes the cache. Omit to always scrape fresh.
Available options:
1d, 3d, 7d, 14d, 30d