# Live

Schemas

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.

- [GETTikTok Live API`/v1/tiktok/live`](https://socialtap.dev/docs/reference/tiktok/live/index.md)
- [GETTwitch Schedule API`/v1/twitch/schedule`](https://socialtap.dev/docs/reference/twitch/schedule/index.md)

## Schema

Single-item endpoints return this object as `data`; list endpoints return an array of them as `data` with a [`page`](https://socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (tiktok, youtube, …). |
| `id` | `string` | Platform-native ID of the broadcast (string; TikTok room ID, YouTube video ID). |
| `url` | `string` (uri) | Public page of the broadcast (TikTok: the host's LIVE page, tiktok.com/@\<username>/live). |
| `status` | `string` | live: on air now; scheduled: announced, not started; ended: over. New values may be added; treat an unknown value as not live.<br>One of `live`, `scheduled`, `ended` |
| `title` | `string` or `null` | The broadcast's title as the host set it. |
| `text` | `string` or `null` | Description as plain text; null where the platform has none. |
| `category` | `string` or `null` | The topic or game the broadcast is filed under, as the platform names it. |
| `host` | `object` | The broadcasting account. |
| `host.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `host.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `host.display_name` | `string` or `null` | Display name shown on the profile. |
| `host.url` | `string` (uri) or `null` | Canonical profile URL. |
| `host.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `host.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `started_at` | `string` (date-time) or `null` | When the broadcast went on air, RFC 3339 UTC; null while scheduled or when not shown. |
| `ended_at` | `string` (date-time) or `null` | When it went off air, RFC 3339 UTC; null while live or scheduled, and when the platform does not say. |
| `scheduled_start_at` | `string` (date-time) or `null` | When a scheduled broadcast is due to start, RFC 3339 UTC; null when none was announced. |
| `thumbnail_url` | `string` (uri) or `null` | Cover or preview image URL. Platform CDN URLs can expire within hours. |
| `post_id` | `string` or `null` | 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. |
| `streams` | `object[]` | 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). |
| `streams[].quality` | `string` or `null` | The platform's label for the rendition (Original, 1080p60, 720p, …). |
| `streams[].format` | `string` | 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.<br>One of `hls`, `dash`, `flv` |
| `streams[].url` | `string` (uri) | Playback URL, signed and expiring: see expires_at. |
| `streams[].expires_at` | `string` (date-time) or `null` | When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown. |
| `streams[].width` | `integer` or `null` | Width in pixels; null for audio-only or when not stated. |
| `streams[].height` | `integer` or `null` | Height in pixels; null for audio-only or when not stated. |
| `streams[].video_codec` | `string` or `null` | Video codec, lowercase (h264, h265); null for audio-only or when not stated. |
| `streams[].bitrate_kbps` | `integer` or `null` | Target bitrate in kbit/s, when the platform states it. |
| `streams[].is_audio_only` | `boolean` or `null` | The rendition carries sound only. |
| `metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `metrics.concurrent_viewer_count` | `integer` or `null` | People watching now; null when not live or not shown. |
| `metrics.view_count` | `integer` or `null` | Cumulative views since the broadcast began (TikTok counts entries into the room). |
| `metrics.like_count` | `integer` or `null` | Likes or hearts; null when hidden or not exposed. |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.tiktok` | `object` or `null` | A TikTok LIVE room's own fields. |
| `platform_specific.tiktok.host_sec_uid` | `string` or `null` | The host's secUid, TikTok's account key that survives a rename. |
| `platform_specific.tiktok.host_follower_count` | `integer` or `null` | The host's follower count at fetch time; null when hidden. |
| `platform_specific.tiktok.stream_id` | `string` or `null` | TikTok's ID of the room's current stream (in its playback links). |
| `platform_specific.tiktok.is_subscriber_only` | `boolean` or `null` | Only the host's paying subscribers can watch. |
| `platform_specific.tiktok.is_age_restricted` | `boolean` or `null` | Viewers must be of age to watch the room; null when the source does not show it. |
| `platform_specific.twitch` | `object` or `null` | A Twitch broadcast's own fields. |
| `platform_specific.twitch.scheduled_end_at` | `string` (date-time) or `null` | When the scheduled broadcast is due to end, RFC 3339 UTC; null when the channel set no end. |
| `platform_specific.twitch.is_cancelled` | `boolean` or `null` | True when the channel cancelled this slot. Twitch still lists it, and its status stays scheduled. |
| `platform_specific.twitch.cancellation_ends_at` | `string` (date-time) or `null` | When the cancellation of this slot lapses, RFC 3339 UTC; null when it is not cancelled. |
| `platform_specific.twitch.base_segment_id` | `string` or `null` | Twitch's ID of the recurring slot, the same every week; id names this week's occurrence. |
| `platform_specific.twitch.categories` | `object[]` | What the slot is filed under, whose first name is category; \[\] when the channel set none. |
| `platform_specific.twitch.categories[].id` | `string` or `null` | Twitch's ID of the category. |
| `platform_specific.twitch.categories[].name` | `string` or `null` | Its name (Just Chatting). |
| `platform_specific.twitch.categories[].slug` | `string` or `null` | Its name in links (twitch.tv/directory/category/just-chatting). |
| `platform_specific.twitch.categories[].box_art_url` | `string` (uri) or `null` | The category's cover image. |
| `platform_specific.twitch.repeat_ends_after_count` | `integer` or `null` | 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. |
| `platform_specific.twitch.vacation` | `object` or `null` | The channel's latest break from its schedule, as Twitch keeps it: it can be long over. Null when it has none. |
| `platform_specific.twitch.vacation.start_at` | `string` (date-time) or `null` | When the break starts, RFC 3339 UTC. |
| `platform_specific.twitch.vacation.end_at` | `string` (date-time) or `null` | When the break ends, RFC 3339 UTC. |
| `platform_specific.twitch.vacation.reason` | `string` or `null` | Twitch's word for the break, lowercase (vacation). |
| `approximate_fields` | `string[]` | 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_fields` | `string[]` | 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](https://socialtap.dev/docs/errors/index.md) 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. |

---

[HTML version](https://socialtap.dev/resources/live/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)