Schemas

Live

Live broadcasts (TikTok LIVE rooms, live streams) with their host, status, start and end, people watching and stream links.

Endpoints

2 endpoints return livestreams on TikTok and Twitch.

Schema

Single-item endpoints return this object as data; list endpoints return an array of them as data with a page object. The standard meta comes with every response.

platformstring

Platform ID (tiktok, youtube, …).

idstring

Platform-native ID of the broadcast (string; TikTok room ID, YouTube video ID).

urlstring uri

Public page of the broadcast (TikTok: the host's LIVE page, tiktok.com/@<username>/live).

statusstring

live: on air now; scheduled: announced, not started; ended: over. New values may be added; treat an unknown value as not live.

One oflivescheduledended

titlestringnullable

The broadcast's title as the host set it.

textstringnullable

Description as plain text; null where the platform has none.

categorystringnullable

The topic or game the broadcast is filed under, as the platform names it.

hostobject

The broadcasting account.

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

started_atstring date-timenullable

When the broadcast went on air, RFC 3339 UTC; null while scheduled or when not shown.

ended_atstring date-timenullable

When it went off air, RFC 3339 UTC; null while live or scheduled, and when the platform does not say.

scheduled_start_atstring date-timenullable

When a scheduled broadcast is due to start, RFC 3339 UTC; null when none was announced.

thumbnail_urlstring urinullable

Cover or preview image URL. Platform CDN URLs can expire within hours.

post_idstringnullable

ID of the post the platform keeps the broadcast as (equals post.id: a YouTube or Rumble video); null when it keeps none (TikTok LIVE) or none yet.

streamsobject[]

Playback links of the broadcast while live, one per rendition and format, best first; [] when not live or when the platform's links only work from SocialTap's network (YouTube).

Show 9 child fields

qualitystringnullable

The platform's label for the rendition (Original, 1080p60, 720p, …).

formatstring

Delivery format of url: hls (an .m3u8 playlist), dash (an .mpd manifest, TikTok's CMAF) or flv (HTTP-FLV). New values may be added; treat unknown values as other.

One ofhlsdashflv

urlstring uri

Playback URL, signed and expiring: see expires_at.

expires_atstring date-timenullable

When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown.

widthintegernullable

Width in pixels; null for audio-only or when not stated.

heightintegernullable

Height in pixels; null for audio-only or when not stated.

video_codecstringnullable

Video codec, lowercase (h264, h265); null for audio-only or when not stated.

bitrate_kbpsintegernullable

Target bitrate in kbit/s, when the platform states it.

is_audio_onlybooleannullable

The rendition carries sound only.

metricsobject

Counts at fetch time; null = hidden or not exposed, 0 = zero.

Show 3 child fields

concurrent_viewer_countintegernullable

People watching now; null when not live or not shown.

view_countintegernullable

Cumulative views since the broadcast began (TikTok counts entries into the room).

like_countintegernullable

Likes or hearts; null when hidden or not exposed.

platform_specificobject

Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.

Show 2 child fields

tiktokobjectnullable

A TikTok LIVE room's own fields.

Show 5 child fields

host_sec_uidstringnullable

The host's secUid, TikTok's account key that survives a rename.

host_follower_countintegernullable

The host's follower count at fetch time; null when hidden.

stream_idstringnullable

TikTok's ID of the room's current stream (in its playback links).

is_subscriber_onlybooleannullable

Only the host's paying subscribers can watch.

is_age_restrictedbooleannullable

Viewers must be of age to watch the room; null when the source does not show it.

twitchobjectnullable

A Twitch broadcast's own fields.

Show 7 child fields

scheduled_end_atstring date-timenullable

When the scheduled broadcast is due to end, RFC 3339 UTC; null when the channel set no end.

is_cancelledbooleannullable

True when the channel cancelled this slot. Twitch still lists it, and its status stays scheduled.

cancellation_ends_atstring date-timenullable

When the cancellation of this slot lapses, RFC 3339 UTC; null when it is not cancelled.

base_segment_idstringnullable

Twitch's ID of the recurring slot, the same every week; id names this week's occurrence.

categoriesobject[]

What the slot is filed under, whose first name is category; [] when the channel set none.

Show 4 child fields

idstringnullable

Twitch's ID of the category.

namestringnullable

Its name (Just Chatting).

slugstringnullable

Its name in links (twitch.tv/directory/category/just-chatting).

box_art_urlstring urinullable

The category's cover image.

repeat_ends_after_countintegernullable

How many times the slot airs before it stops repeating: 1 is a one-off. 0 or null: the channel set no end, and it repeats every week.

vacationobjectnullable

The channel's latest break from its schedule, as Twitch keeps it: it can be long over. Null when it has none.

Show 3 child fields

start_atstring date-timenullable

When the break starts, RFC 3339 UTC.

end_atstring date-timenullable

When the break ends, RFC 3339 UTC.

reasonstringnullable

Twitch's word for the break, lowercase (vacation).

approximate_fieldsstring[]

JSON paths of values rounded by the platform or parsed from display text. A list path means the list may be incomplete. [] when all exact.

unknown_fieldsstring[]

JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.

Item errors

Besides the request-level errors every endpoint can return, live endpoints return:

Code	HTTP	Retry	Meaning	What to do
`not_found`	404	No	The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why).	Check the link or ID. Do not retry.
`private_or_unavailable`	403	No	The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code.	Only public items can be fetched. Do not retry.
`no_live`	404	No	The account exists but has no live broadcast to show: nothing on air or scheduled, and no past broadcast the platform still shows.	Do not retry now. Ask again later, when the account may be live.

Example (TikTok)

{
  "data": {
    "approximate_fields": [],
    "category": null,
    "ended_at": null,
    "host": {
      "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/f569c9cd13cf1ccee624a4ae1b0b4c4e~tplv-tiktokx-cropcenter:1080:1080.webp?dr=9640&refresh_token=b70569e5&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=fdd36af4&idc=useast5",
      "display_name": "Al Jazeera English",
      "id": "7074562477175424046",
      "is_verified": true,
      "url": "https://www.tiktok.com/@aljazeeraenglish",
      "username": "aljazeeraenglish"
    },
    "id": "7703236637299444493",
    "metrics": {
      "concurrent_viewer_count": 4935,
      "like_count": null,
      "view_count": 926646
    },
    "platform": "tiktok",
    "platform_specific": {
      "tiktok": {
        "host_follower_count": 16752217,
        "host_sec_uid": "MS4wLjABAAAAtS2tPZtfESngqzjzrwwUu0M1LUlx1MjODxCDecgBvwBcyquIg56vBb_2I0BaW574",
        "is_age_restricted": null,
        "is_subscriber_only": false,
        "stream_id": "3579127593564111804"
      }
    },
    "post_id": null,
    "scheduled_start_at": null,
    "started_at": "2026-11-01T16:14:18Z",
    "status": "live",
    "streams": [
      {
        "bitrate_kbps": 10671,
        "expires_at": "2026-10-25T18:00:00Z",
        "format": "hls",
        "height": 1080,
        "is_audio_only": false,
        "quality": "Original",
        "url": "https://pull-hls-f16-tt01.tiktokcdn-us.com/game/stream-3579127593564111804/index.m3u8?expire=4070908800&sign=SCRUBBED",
        "video_codec": "h264",
        "width": 1920
      },
      {
        "bitrate_kbps": 10671,
        "expires_at": "2026-10-25T18:00:00Z",
        "format": "dash",
        "height": 1080,
        "is_audio_only": false,
        "quality": "Original",
        "url": "https://pull-f5-tt01.tiktokcdn-us.com/game/stream-3579127593564111804/index.mpd?auth_mode=2&expire=4070908800&sign=SCRUBBED",
        "video_codec": "h264",
        "width": 1920
      },
      {
        "bitrate_kbps": 10671,
        "expires_at": "2026-10-25T18:00:00Z",
        "format": "flv",
        "height": 1080,
        "is_audio_only": false,
        "quality": "Original",
        "url": "https://pull-f5-tt01.tiktokcdn-us.com/game/stream-3579127593564111804.flv?expire=4070908800&sign=SCRUBBED",
        "video_codec": "h264",
        "width": 1920
      }
    ],
    "text": null,
    "thumbnail_url": "https://p16-webcast.tiktokcdn-us.com/webcast-oci-tx/7628418490097126158~tplv-obj.image",
    "title": "Al Jazeera English TikTok LIVE",
    "unknown_fields": [],
    "url": "https://www.tiktok.com/@aljazeeraenglish/live"
  },
  "meta": {
    "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
    "platform": "tiktok",
    "source": "api",
    "is_cached": false,
    "credits_charged": 1,
    "latency_ms": 476,
    "fetched_at": "2026-10-25T12:00:00Z",
    "input": {
      "kind": "profile",
      "id": "7703236637299444493",
      "url": "https://www.tiktok.com/@aljazeeraenglish/live"
    },
    "credits_remaining": 9999,
    "client_request_id": null,
    "warnings": []
  }
}

Long arrays and strings are shortened for display.