> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scraperize.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
**Cost: 1 credit** per successful request. Errors and cache hits (`cache_max_age`) are free.
Paste this into ChatGPT, Claude or your coding assistant to generate working code for this endpoint (use the copy button).
```text 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.
```
## OpenAPI
````yaml /api-reference/openapi.json get /v1/tiktok/user/live
openapi: 3.0.3
info:
title: Scraperize API
version: 1.0.0
description: >-
Extract public data from social media platforms as clean JSON. Endpoints are
split by platform and by what they return, e.g. `GET /v1/twitter/tweet`.
## Authentication
Send your API key in the `x-api-key` header (or `Authorization: Bearer
`). Create keys in your dashboard.
## Credits
Each successful live scrape costs **1 credit**. Credits are prepaid and
never expire.
## Caching
Every endpoint accepts an optional `cache_max_age`
(`1d`|`3d`|`7d`|`14d`|`30d`). A cache hit within that window is returned for
**0 credits**.
## Responses
Success returns `{ "data": …, "meta": { "requestId", … } }`. Errors return
`{ "error": { "code", "message", "requestId" } }` with a matching HTTP
status. `meta` on a scrape carries `creditsCharged`, `creditsRemaining`,
`cached`, and (on a hit) `cachedAt`.
## Rate limits
Requests are limited per team per minute; over the limit returns `429` with
a `Retry-After` header.
servers:
- url: https://api.scraperize.com
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Twitter
description: Twitter / X scraping endpoints
- name: Facebook
description: Facebook scraping endpoints
- name: Linkme
description: Linkme (link.me) scraping endpoints
- name: Amazon
description: Amazon (creator shop / storefront) scraping endpoints
- name: Linkbio
description: Linkbio (lnk.bio) scraping endpoints
- name: Pillar
description: Pillar (pillar.io) scraping endpoints
- name: Komi
description: Komi (komi.io) scraping endpoints
- name: Linktree
description: Linktree (linktr.ee) scraping endpoints
- name: Kick
description: Kick (kick.com) scraping endpoints
- name: Snapchat
description: Snapchat (snapchat.com) scraping endpoints
- name: Telegram
description: Telegram (t.me) scraping endpoints
- name: LinkedIn
description: LinkedIn scraping endpoints
- name: Twitch
description: Twitch scraping endpoints
- name: TikTok
description: TikTok (tiktok.com) scraping endpoints
paths:
/v1/tiktok/user/live:
get:
tags:
- TikTok
summary: LIVE stream
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.
parameters:
- name: handle
in: query
required: true
description: >-
The TikTok username (with or without a leading @, or a
tiktok.com/@username URL).
schema:
type: string
example: pepper_979
- name: cache_max_age
in: query
required: false
description: >-
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.
schema:
type: string
enum:
- 1d
- 3d
- 7d
- 14d
- 30d
example: 7d
responses:
'200':
description: The account and its LIVE (or its most recent LIVE when offline).
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
isLive:
type: boolean
user:
type: object
properties:
id:
type: string
nullable: true
secUid:
type: string
nullable: true
handle:
type: string
nickname:
type: string
nullable: true
bio:
type: string
nullable: true
avatarUrl:
type: string
nullable: true
verified:
type: boolean
isPrivate:
type: boolean
followerCount:
type: integer
nullable: true
followingCount:
type: integer
nullable: true
profileUrl:
type: string
liveUrl:
type: string
live:
type: object
nullable: true
properties:
roomId:
type: string
streamId:
type: string
nullable: true
title:
type: string
nullable: true
shareUrl:
type: string
nullable: true
coverUrl:
type: string
nullable: true
startedAt:
type: string
format: date-time
nullable: true
viewerCount:
type: integer
nullable: true
totalViewers:
type: integer
nullable: true
newFollowers:
type: integer
nullable: true
category:
type: object
nullable: true
game:
type: object
nullable: true
broadcastType:
type: string
nullable: true
enum:
- camera
- screen
- streaming_software
- audio
isCoHosting:
type: boolean
battle:
type: object
nullable: true
topGifters:
type: array
items:
type: object
ageRestricted:
type: boolean
subscriberOnly:
type: boolean
isPaidEvent:
type: boolean
hasShop:
type: boolean
shopProductCount:
type: integer
nullable: true
chatEnabled:
type: boolean
nullable: true
giftsEnabled:
type: boolean
nullable: true
streams:
type: array
items:
type: object
lastLive:
type: object
nullable: true
fetchedAt:
type: string
format: date-time
meta:
type: object
description: >-
requestId + credit/caching metadata (creditsCharged,
creditsRemaining, cached, cachedAt).
required:
- data
- meta
example:
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
'401':
description: Missing, invalid, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: API key required — pass it in the `x-api-key` header.
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
'402':
description: Not enough credits for this request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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
'404':
description: No TikTok account with that username.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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
'422':
description: Invalid query parameters (missing or malformed handle).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: VALIDATION_ERROR
message: Request validation failed
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
details:
- path: url
message: Required
'429':
description: Over the per-minute rate limit — honour `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: RATE_LIMITED
message: >-
Rate limit exceeded — max 100 requests per 60s. Retry in
~30s.
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
'503':
description: >-
Temporarily unavailable — retry after `Retry-After`. `error.code`
tells you why: `UPSTREAM_BLOCKED` (the source blocked this request),
`EXTRACTION_FAILED` (the source returned unexpected data),
`PLATFORM_UNAVAILABLE` (the source is down), or
`SERVICE_UNAVAILABLE` (we are at capacity).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UPSTREAM_BLOCKED
message: >-
The source is temporarily unavailable. Please try again
shortly.
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
components:
schemas:
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: NOT_FOUND
message:
type: string
example: The requested content was not found.
requestId:
type: string
example: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
details:
type: array
items:
type: object
description: Present on validation errors.
required:
- code
- message
- requestId
required:
- error
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Your API key. Send it in the `x-api-key` header (or `Authorization:
Bearer `). Create and manage keys from your dashboard.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.