Get one TikTok LIVE room (sync)

curl --request POST \
  --url https://api.vidnavigator.com/v1/tiktok/live/room \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "room_id": "7705498471838665494",
  "username": "tiktok",
  "url": "https://www.tiktok.com/@tiktok/live",
  "include_comments": false,
  "comments_limit": 50,
  "include_stream_urls": true,
  "include_usage": false
}
'

import requests

url = "https://api.vidnavigator.com/v1/tiktok/live/room"

payload = {
    "room_id": "7705498471838665494",
    "username": "tiktok",
    "url": "https://www.tiktok.com/@tiktok/live",
    "include_comments": False,
    "comments_limit": 50,
    "include_stream_urls": True,
    "include_usage": False
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    room_id: '7705498471838665494',
    username: 'tiktok',
    url: 'https://www.tiktok.com/@tiktok/live',
    include_comments: false,
    comments_limit: 50,
    include_stream_urls: true,
    include_usage: false
  })
};

fetch('https://api.vidnavigator.com/v1/tiktok/live/room', 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.vidnavigator.com/v1/tiktok/live/room",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'room_id' => '7705498471838665494',
    'username' => 'tiktok',
    'url' => 'https://www.tiktok.com/@tiktok/live',
    'include_comments' => false,
    'comments_limit' => 50,
    'include_stream_urls' => true,
    'include_usage' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vidnavigator.com/v1/tiktok/live/room"

	payload := strings.NewReader("{\n  \"room_id\": \"7705498471838665494\",\n  \"username\": \"tiktok\",\n  \"url\": \"https://www.tiktok.com/@tiktok/live\",\n  \"include_comments\": false,\n  \"comments_limit\": 50,\n  \"include_stream_urls\": true,\n  \"include_usage\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vidnavigator.com/v1/tiktok/live/room")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"room_id\": \"7705498471838665494\",\n  \"username\": \"tiktok\",\n  \"url\": \"https://www.tiktok.com/@tiktok/live\",\n  \"include_comments\": false,\n  \"comments_limit\": 50,\n  \"include_stream_urls\": true,\n  \"include_usage\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vidnavigator.com/v1/tiktok/live/room")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"room_id\": \"7705498471838665494\",\n  \"username\": \"tiktok\",\n  \"url\": \"https://www.tiktok.com/@tiktok/live\",\n  \"include_comments\": false,\n  \"comments_limit\": 50,\n  \"include_stream_urls\": true,\n  \"include_usage\": false\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "data": {
    "room": {
      "id": "7704440240265644830",
      "title": "Ranked grind #fortnite",
      "url": "https://www.tiktok.com/@creator/live",
      "status": "live",
      "ended_at": "2023-11-07T05:31:56Z",
      "share_url": "https://m.tiktok.com/share/live/7705498471838665494",
      "started_at": "2023-11-07T05:31:56Z",
      "author": {
        "id": "<string>",
        "unique_id": "<string>",
        "nickname": "<string>",
        "sec_uid": "<string>",
        "followers": 123,
        "avatar_url": "<string>",
        "bio": "<string>",
        "following": 123
      },
      "stats": {
        "viewers": 123,
        "total_viewers": 123,
        "new_followers": 123
      },
      "hashtags": [
        "fortnite"
      ],
      "category": "Gaming",
      "game_tags": [
        "Fortnite"
      ],
      "cover_url": "<string>",
      "stream_urls": {
        "default_quality": "hd",
        "flv": {
          "hd": "https://pull-f5-tt01.tiktokcdn-us.com/game/stream-123_hd.flv?expire=1795089584&sign=..."
        },
        "hls": {
          "hd": "https://pull-hls-f16-tt01.tiktokcdn-us.com/game/stream-123_hd/index.m3u8?expire=1795089584&sign=..."
        },
        "audio_only": "<string>",
        "expires_at": "2023-11-07T05:31:56Z"
      },
      "age_restricted": true,
      "subscribers_only": true,
      "chat_enabled": true,
      "products": 123
    },
    "comments": [
      {
        "id": "7705553654292319009",
        "text": "Where was this filmed?",
        "language": "fr",
        "created_at": "2023-11-07T05:31:56Z",
        "author": {
          "id": "<string>",
          "unique_id": "<string>",
          "nickname": "<string>",
          "sec_uid": "<string>",
          "followers": 123,
          "avatar_url": "<string>"
        },
        "author_is_follower": true,
        "author_is_moderator": true,
        "author_is_subscriber": true
      }
    ],
    "pinned_comment": {
      "id": "7705553654292319009",
      "text": "Where was this filmed?",
      "language": "fr",
      "created_at": "2023-11-07T05:31:56Z",
      "author": {
        "id": "<string>",
        "unique_id": "<string>",
        "nickname": "<string>",
        "sec_uid": "<string>",
        "followers": 123,
        "avatar_url": "<string>"
      },
      "author_is_follower": true,
      "author_is_moderator": true,
      "author_is_subscriber": true
    },
    "intro": "<string>",
    "top_viewers": [
      {
        "rank": 1,
        "score": 123,
        "user": {
          "id": "<string>",
          "unique_id": "<string>",
          "nickname": "<string>",
          "sec_uid": "<string>",
          "followers": 123,
          "avatar_url": "<string>"
        }
      }
    ]
  },
  "usage": {
    "charges": [
      {
        "service_type": "standard_request",
        "quantity": 123,
        "credits": 123,
        "waived": true,
        "credits_saved": 123,
        "tokens": {
          "prompt_tokens": 123,
          "completion_tokens": 123,
          "total_tokens": 123
        }
      }
    ],
    "total_credits": 123,
    "waived": {
      "credits_saved": 123
    }
  }
}

{
  "status": "error",
  "error": "<string>",
  "message": "<string>"
}

{
  "status": "error",
  "error": "limit_exceeded",
  "message": "<string>"
}

{
  "status": "error",
  "error": "live_not_found",
  "message": "<string>",
  "usage": {
    "charges": [
      {
        "service_type": "standard_request",
        "quantity": 123,
        "credits": 123,
        "waived": true,
        "credits_saved": 123,
        "tokens": {
          "prompt_tokens": 123,
          "completion_tokens": 123,
          "total_tokens": 123
        }
      }
    ],
    "total_credits": 123,
    "waived": {
      "credits_saved": 123
    }
  }
}

{
  "status": "error",
  "error": "limit_exceeded",
  "message": "<string>",
  "usage": 123,
  "limit": 123
}

{
  "status": "error",
  "error": "metadata_fetch_failed",
  "message": "<string>"
}

{
  "status": "error",
  "error": "live_room_unavailable",
  "message": "<string>",
  "usage": {
    "charges": [
      {
        "service_type": "standard_request",
        "quantity": 123,
        "credits": 123,
        "waived": true,
        "credits_saved": 123,
        "tokens": {
          "prompt_tokens": 123,
          "completion_tokens": 123,
          "total_tokens": 123
        }
      }
    ],
    "total_credits": 123,
    "waived": {
      "credits_saved": 123
    }
  }
}

Online media

TikTok LIVE Room

Get one TikTok LIVE room, synchronously: by room_id, by streamer (username), or by LIVE URL. Send exactly one of the three.

The room comes with its current state: whether it is live or has ended (and when), viewers now and since the start, followers gained during the LIVE, the streamer’s bio, whether chat is on or the LIVE is for subscribers only, the number of products on sale, and playback URLs. A username returns the streamer’s current LIVE, or their last one when they are offline (status: "ended").

With include_comments: true, the response also has the latest comments (up to 50, newest first), the pinned comment, the LIVE’s intro text and its top viewers. TikTok only keeps the latest ~50 comments of a LIVE available: earlier ones cannot be retrieved. A room that has ended returns no comments.

The likes, comment count and share count of a room are not available here: POST /tiktok/live/search returns them for each room it finds.

Usually answers in 1-5 s, sometimes up to ~30 s; allow a client timeout of 120 s.

POST

tiktok

live

room

Get one TikTok LIVE room (sync)

curl --request POST \
  --url https://api.vidnavigator.com/v1/tiktok/live/room \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "room_id": "7705498471838665494",
  "username": "tiktok",
  "url": "https://www.tiktok.com/@tiktok/live",
  "include_comments": false,
  "comments_limit": 50,
  "include_stream_urls": true,
  "include_usage": false
}
'

import requests

url = "https://api.vidnavigator.com/v1/tiktok/live/room"

payload = {
    "room_id": "7705498471838665494",
    "username": "tiktok",
    "url": "https://www.tiktok.com/@tiktok/live",
    "include_comments": False,
    "comments_limit": 50,
    "include_stream_urls": True,
    "include_usage": False
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    room_id: '7705498471838665494',
    username: 'tiktok',
    url: 'https://www.tiktok.com/@tiktok/live',
    include_comments: false,
    comments_limit: 50,
    include_stream_urls: true,
    include_usage: false
  })
};

fetch('https://api.vidnavigator.com/v1/tiktok/live/room', 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.vidnavigator.com/v1/tiktok/live/room",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'room_id' => '7705498471838665494',
    'username' => 'tiktok',
    'url' => 'https://www.tiktok.com/@tiktok/live',
    'include_comments' => false,
    'comments_limit' => 50,
    'include_stream_urls' => true,
    'include_usage' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vidnavigator.com/v1/tiktok/live/room"

	payload := strings.NewReader("{\n  \"room_id\": \"7705498471838665494\",\n  \"username\": \"tiktok\",\n  \"url\": \"https://www.tiktok.com/@tiktok/live\",\n  \"include_comments\": false,\n  \"comments_limit\": 50,\n  \"include_stream_urls\": true,\n  \"include_usage\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vidnavigator.com/v1/tiktok/live/room")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"room_id\": \"7705498471838665494\",\n  \"username\": \"tiktok\",\n  \"url\": \"https://www.tiktok.com/@tiktok/live\",\n  \"include_comments\": false,\n  \"comments_limit\": 50,\n  \"include_stream_urls\": true,\n  \"include_usage\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vidnavigator.com/v1/tiktok/live/room")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"room_id\": \"7705498471838665494\",\n  \"username\": \"tiktok\",\n  \"url\": \"https://www.tiktok.com/@tiktok/live\",\n  \"include_comments\": false,\n  \"comments_limit\": 50,\n  \"include_stream_urls\": true,\n  \"include_usage\": false\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "data": {
    "room": {
      "id": "7704440240265644830",
      "title": "Ranked grind #fortnite",
      "url": "https://www.tiktok.com/@creator/live",
      "status": "live",
      "ended_at": "2023-11-07T05:31:56Z",
      "share_url": "https://m.tiktok.com/share/live/7705498471838665494",
      "started_at": "2023-11-07T05:31:56Z",
      "author": {
        "id": "<string>",
        "unique_id": "<string>",
        "nickname": "<string>",
        "sec_uid": "<string>",
        "followers": 123,
        "avatar_url": "<string>",
        "bio": "<string>",
        "following": 123
      },
      "stats": {
        "viewers": 123,
        "total_viewers": 123,
        "new_followers": 123
      },
      "hashtags": [
        "fortnite"
      ],
      "category": "Gaming",
      "game_tags": [
        "Fortnite"
      ],
      "cover_url": "<string>",
      "stream_urls": {
        "default_quality": "hd",
        "flv": {
          "hd": "https://pull-f5-tt01.tiktokcdn-us.com/game/stream-123_hd.flv?expire=1795089584&sign=..."
        },
        "hls": {
          "hd": "https://pull-hls-f16-tt01.tiktokcdn-us.com/game/stream-123_hd/index.m3u8?expire=1795089584&sign=..."
        },
        "audio_only": "<string>",
        "expires_at": "2023-11-07T05:31:56Z"
      },
      "age_restricted": true,
      "subscribers_only": true,
      "chat_enabled": true,
      "products": 123
    },
    "comments": [
      {
        "id": "7705553654292319009",
        "text": "Where was this filmed?",
        "language": "fr",
        "created_at": "2023-11-07T05:31:56Z",
        "author": {
          "id": "<string>",
          "unique_id": "<string>",
          "nickname": "<string>",
          "sec_uid": "<string>",
          "followers": 123,
          "avatar_url": "<string>"
        },
        "author_is_follower": true,
        "author_is_moderator": true,
        "author_is_subscriber": true
      }
    ],
    "pinned_comment": {
      "id": "7705553654292319009",
      "text": "Where was this filmed?",
      "language": "fr",
      "created_at": "2023-11-07T05:31:56Z",
      "author": {
        "id": "<string>",
        "unique_id": "<string>",
        "nickname": "<string>",
        "sec_uid": "<string>",
        "followers": 123,
        "avatar_url": "<string>"
      },
      "author_is_follower": true,
      "author_is_moderator": true,
      "author_is_subscriber": true
    },
    "intro": "<string>",
    "top_viewers": [
      {
        "rank": 1,
        "score": 123,
        "user": {
          "id": "<string>",
          "unique_id": "<string>",
          "nickname": "<string>",
          "sec_uid": "<string>",
          "followers": 123,
          "avatar_url": "<string>"
        }
      }
    ]
  },
  "usage": {
    "charges": [
      {
        "service_type": "standard_request",
        "quantity": 123,
        "credits": 123,
        "waived": true,
        "credits_saved": 123,
        "tokens": {
          "prompt_tokens": 123,
          "completion_tokens": 123,
          "total_tokens": 123
        }
      }
    ],
    "total_credits": 123,
    "waived": {
      "credits_saved": 123
    }
  }
}

{
  "status": "error",
  "error": "<string>",
  "message": "<string>"
}

{
  "status": "error",
  "error": "limit_exceeded",
  "message": "<string>"
}

{
  "status": "error",
  "error": "live_not_found",
  "message": "<string>",
  "usage": {
    "charges": [
      {
        "service_type": "standard_request",
        "quantity": 123,
        "credits": 123,
        "waived": true,
        "credits_saved": 123,
        "tokens": {
          "prompt_tokens": 123,
          "completion_tokens": 123,
          "total_tokens": 123
        }
      }
    ],
    "total_credits": 123,
    "waived": {
      "credits_saved": 123
    }
  }
}

{
  "status": "error",
  "error": "limit_exceeded",
  "message": "<string>",
  "usage": 123,
  "limit": 123
}

{
  "status": "error",
  "error": "metadata_fetch_failed",
  "message": "<string>"
}

{
  "status": "error",
  "error": "live_room_unavailable",
  "message": "<string>",
  "usage": {
    "charges": [
      {
        "service_type": "standard_request",
        "quantity": 123,
        "credits": 123,
        "waived": true,
        "credits_saved": 123,
        "tokens": {
          "prompt_tokens": 123,
          "completion_tokens": 123,
          "total_tokens": 123
        }
      }
    ],
    "total_credits": 123,
    "waived": {
      "credits_saved": 123
    }
  }
}

Get one TikTok LIVE room right away, by room ID, by streamer or by LIVE URL, with its latest comments on request.

Overview

This endpoint is synchronous: it answers with the room, no task to poll. Use it to:

check whether a streamer is live right now, and with how many viewers;
follow a room found by TikTok LIVE Search: is it still live, when did it end;
read a LIVE’s latest comments, its pinned comment and its top viewers.

The room comes with the fields of a LIVE search room (title, streamer, category, hashtags, stream URLs, …) plus its status (live or ended), the time it ended, the followers the streamer gained during the LIVE, the streamer’s bio, whether chat is on or the LIVE is for subscribers only, and the number of products on sale.

A username returns the streamer’s current LIVE, or their last one when they are offline (status: "ended").
It usually answers in 1 to 5 seconds, sometimes up to ~30 seconds. Allow a client timeout of 120 seconds.

Comments: TikTok only keeps the latest ~50 comments of a LIVE available. Earlier comments cannot be retrieved, by this endpoint or any other. A room that has ended returns no comments.

Likes, comment count and share count are not part of a single room: TikTok does not provide them there. TikTok LIVE Search returns them for each room it finds.

Billing

1 residential_request per room, 2 with include_comments.
When the room has ended, the comments are not billed (1 in total).
A room or account that does not exist (404 live_not_found) and a failed lookup (502 live_room_unavailable) are not billed.
Pass include_usage: true to get the usage block in the response.

Request Parameters

Send exactly one of room_id, username or url.

Parameter	Type	Required	Description
`room_id`	string	One of three	A LIVE room ID, e.g. the `id` of a LIVE search room. Send it as a string: room IDs have more digits than a JavaScript number holds.
`username`	string	One of three	The streamer’s TikTok username, with or without `@`.
`url`	string	One of three	A LIVE URL (`https://www.tiktok.com/@username/live`), a profile URL (`https://www.tiktok.com/@username`), or a room’s `share_url` (`https://m.tiktok.com/share/live/<room_id>`). Short `vm.tiktok.com` links are not accepted.
`include_comments`	boolean	No	Default `false`. Also return the latest comments, the pinned comment, the intro and the top viewers. Bills a second `residential_request`.
`comments_limit`	integer	No	Maximum comments returned with `include_comments`, from `1` to `50`. Default `50`.
`include_stream_urls`	boolean	No	Default `true`: the room carries its `stream_urls`. Pass `false` to leave them out.
`include_usage`	boolean	No	Default `false`. Add the `usage` block (charges of this request) to the response.

Example Usage

curl -X POST "https://api.vidnavigator.com/v1/tiktok/live/room" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "creator",
    "include_comments": true,
    "comments_limit": 20
  }'

from vidnavigator import VidNavigatorClient

client = VidNavigatorClient(api_key="YOUR_API_KEY")
resp = client.get_tiktok_live_room(username="creator", include_comments=True, comments_limit=20)

room = resp.data.room
print(room.status, room.title, room.stats.viewers)
for comment in resp.data.comments or []:
    print(comment.created_at, comment.author.unique_id, comment.text)

import { VidNavigatorClient } from 'vidnavigator';

const vn = new VidNavigatorClient({ apiKey: 'YOUR_API_KEY' });
const { room, comments } = await vn.getTikTokLiveRoom({ username: 'creator', include_comments: true, comments_limit: 20 });

console.log(room.status, room.title, room.stats?.viewers);
for (const c of comments ?? []) console.log(c.created_at, c.author?.unique_id, c.text);

Success Response (200)

{
  "status": "success",
  "data": {
    "room": {
      "id": "7705498471838665494",
      "title": "Late night Q&A",
      "url": "https://www.tiktok.com/@creator/live",
      "status": "live",
      "ended_at": null,
      "share_url": "https://m.tiktok.com/share/live/7705498471838665494",
      "started_at": "2026-11-07T20:12:05Z",
      "author": {
        "id": "6628548115959152646",
        "unique_id": "creator",
        "nickname": "Creator",
        "sec_uid": "MS4wLjABAAAA...",
        "followers": 18867,
        "avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/...",
        "bio": "Live every night at 9",
        "following": 312
      },
      "stats": {
        "viewers": 936,
        "total_viewers": 4005,
        "new_followers": 12
      },
      "hashtags": [],
      "category": null,
      "game_tags": [],
      "cover_url": "https://p16-common-sign.tiktokcdn-eu.com/...",
      "stream_urls": {
        "default_quality": "hd",
        "flv": { "hd": "https://pull-f5-tt03.tiktokcdn.com/stage/stream-123_hd.flv?expire=1795089584&sign=..." },
        "hls": { "hd": "https://pull-hls-f16-tt03.tiktokcdn.com/stage/stream-123_hd/index.m3u8?expire=1795089584&sign=..." },
        "audio_only": "https://pull-f5-tt03.tiktokcdn.com/stage/stream-123.flv?expire=1795089584&sign=...&only_audio=1",
        "expires_at": "2026-11-21T20:12:05Z"
      },
      "age_restricted": false,
      "subscribers_only": false,
      "chat_enabled": true,
      "products": 0
    },
    "comments": [
      {
        "id": "7705553654292319009",
        "text": "Where was this filmed?",
        "language": "en",
        "created_at": "2026-11-07T22:03:40.989Z",
        "author": {
          "id": "7272313064443167776",
          "unique_id": "viewer_one",
          "nickname": "Viewer One",
          "sec_uid": "MS4wLjABAAAA...",
          "followers": 831,
          "avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/..."
        },
        "author_is_follower": true,
        "author_is_moderator": false,
        "author_is_subscriber": false
      }
    ],
    "pinned_comment": {
      "id": "7705548209969220385",
      "text": "Questions in the chat, answers live!",
      "language": "en",
      "created_at": "2026-11-07T21:42:35.069Z",
      "author": { "unique_id": "creator", "nickname": "Creator", "followers": 18867 },
      "author_is_follower": false,
      "author_is_moderator": false,
      "author_is_subscriber": false
    },
    "intro": "Every night: your questions, my answers.",
    "top_viewers": [
      { "rank": 1, "score": 300, "user": { "unique_id": "viewer_two", "nickname": "Viewer Two", "followers": 120 } }
    ]
  },
  "usage": {
    "charges": [
      { "service_type": "residential_request", "quantity": 2, "credits": 0.01 }
    ],
    "total_credits": 0.01
  }
}

comments, pinned_comment, intro and top_viewers are present only with include_comments: true; usage only with include_usage: true.

Understanding the Response

`room`

The fields of a LIVE search room, plus:

Field	Description
`status`	`live` while broadcasting, `ended` once finished
`ended_at`	When the LIVE ended (UTC, ISO 8601); `null` while it is live
`share_url`	The room’s share link. It can be passed back as `url`.
`author.bio`	The streamer’s bio
`author.following`	Accounts the streamer follows
`stats`	`viewers` (watching now, `0` once ended), `total_viewers` (since the LIVE started), `new_followers` (followers gained during this LIVE). No `likes`, `comments` or `shares`: see the note above.
`age_restricted`	The LIVE is restricted to adult viewers
`subscribers_only`	Only the streamer’s paying subscribers can watch
`chat_enabled`	Viewers can comment
`products`	Number of products on sale in the LIVE (`0` when none)

`comments`

The latest comments, newest first, at most comments_limit.

Field	Description
`id`	Comment ID
`text`	The comment
`language`	Language TikTok detected (ISO 639-1), or `null`
`created_at`	When it was posted (UTC, ISO 8601, milliseconds)
`author`	`id`, `unique_id`, `nickname`, `sec_uid`, `followers`, `avatar_url`
`author_is_follower`	The author follows the streamer
`author_is_moderator`	The author moderates this LIVE
`author_is_subscriber`	The author is a paying subscriber of the streamer

`pinned_comment`, `intro`, `top_viewers`

pinned_comment: the comment the streamer pinned, same shape as a comment, or null.
intro: the LIVE’s intro text, if the streamer set one.
top_viewers: the LIVE’s top viewers by gifts sent (rank, score, user), when TikTok shows them. Can be empty.

Error Cases

Status	`error`	When
`400`	`request_body_required`	No JSON body
`400`	`invalid_parameter`	None, or more than one, of `room_id`, `username`, `url`
`400`	`invalid_room_id` / `invalid_username` / `invalid_url`	The room ID, username or URL is malformed
`400`	`invalid_include_comments` / `invalid_comments_limit` / `invalid_include_stream_urls`	Wrong type, or `comments_limit` outside 1-50
`402`	`limit_exceeded`	Not enough credits (checked before TikTok is contacted)
`404`	`live_not_found`	The room ID does not exist, or the account does not exist or has never gone LIVE. Not billed.
`502`	`live_room_unavailable`	TikTok did not serve the room. Retry in a moment. Not billed.

Tips

To follow a LIVE over time, call this endpoint again with the same room_id: each call is a fresh snapshot.
Calling with username is the simplest way to know whether a creator is live now: status tells you, and ended_at when their last LIVE ended.
Likes, comment counts and share counts come with LIVE search results: keep them from the search that found the room.

Authorizations

X-API-Key

string

header

required

API key authentication. Include your VidNavigator API key in the X-API-Key header.

Body

application/json

Exactly one of room_id, username or url.

room_id

string

A LIVE room ID, as a string (it has more digits than a JavaScript number holds), e.g. the id of a POST /tiktok/live/search result.

Pattern: ^[0-9]{1,25}$

Example:

"7705498471838665494"

username

string

The streamer's TikTok username, with or without @.

Example:

"tiktok"

url

string

A LIVE URL (https://www.tiktok.com/@username/live), a profile URL (https://www.tiktok.com/@username), or a room's share_url (https://m.tiktok.com/share/live/<room_id>). Short vm.tiktok.com links are not accepted.

Example:

"https://www.tiktok.com/@tiktok/live"

include_comments

boolean

default:false

Also return the latest comments, the pinned comment, the intro and the top viewers.

comments_limit

integer

default:50

Maximum comments returned with include_comments.

Required range: 1 <= x <= 50

include_stream_urls

boolean

default:true

Include the room's playback URLs (room.stream_urls).

include_usage

boolean

default:false

When true, the response includes the usage block of this request.

Response

The room.

status

enum<string>

Available options:

success

data

object

Show child attributes

usage

object

Per-call usage, returned only when the request sets include_usage=true: the charges of this request, one entry per service_type, and the total credits deducted. A waived charge carries waived: true and credits_saved, with a top-level waived.credits_saved summary.

For endpoints that run an AI analysis (/extract/video, /extract/file, /analyze/video, /analyze/file, /youtube/search), the analysis_request entry carries a nested tokens object with the request's token counts.

Show child attributes

API Documentation

Online media

Local Files

System

TikTok LIVE Room

Overview

Billing

Request Parameters

Example Usage

Success Response (200)

Understanding the Response

`room`

`comments`

`pinned_comment`, `intro`, `top_viewers`

Error Cases

Tips

Authorizations

Body

Response

​Overview

​Billing

​Request Parameters

​Example Usage

​Success Response (200)

​Understanding the Response

​room

​comments

​pinned_comment, intro, top_viewers

​Error Cases

​Tips

Authorizations

Body

Response

Overview

Billing

Request Parameters

Example Usage

Success Response (200)

Understanding the Response

`room`

`comments`

`pinned_comment`, `intro`, `top_viewers`

Error Cases

Tips