# Twitch

Canonical: https://monsterapi.co/docs/twitch

Read public Twitch data at `https://api.monsterapi.co/twitch/api` with a MonsterAPI bearer key. Twitch sign-in isn’t required.

## First request

Set `MONSTERAPI_KEY` to your MonsterAPI key, then request a page of live streams:

```bash
curl -sS 'https://api.monsterapi.co/twitch/api/streams?limit=3' \
  -H "Authorization: Bearer ${MONSTERAPI_KEY}"
```

The response contains a `streams` list and a `data` object with additional Twitch information.
Each stream includes its channel, viewer count and category when available.
The [API reference](https://monsterapi.co/docs/api) lists every endpoint and response field.

## Read response values

In named fields, identifiers are strings and counts are numbers. Missing or incompatible optional values are `null`.
Valid empty strings, lists, and objects stay empty. An optional record is `null` only when all its named fields are `null`.
HLS playback and live chat responses use named fields without `data`.

Use non-null values from these response fields:

| Value         | Response source                                                                                                          | Used by                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| Channel login | [GET `/twitch/api/streams`](https://monsterapi.co/docs/api/twitch-directory#popular-live-streams): `streams[].author.username`                | [GET `/twitch/api/channel/{login}`](https://monsterapi.co/docs/api/twitch-channel#channel-profile) |
| Category slug | [GET `/twitch/api/games`](https://monsterapi.co/docs/api/twitch-directory#all-categories): `categories[].slug`                                | [GET `/twitch/api/game/{name}`](https://monsterapi.co/docs/api/twitch-directory#category-details)  |
| Recording ID  | [GET `/twitch/api/channel/{login}/videos`](https://monsterapi.co/docs/api/twitch-video#channel-recordings): `videos[].id`                     | [GET `/twitch/api/video/{id}`](https://monsterapi.co/docs/api/twitch-video#recording-metadata)     |
| Clip slug     | [GET `/twitch/api/channel/{login}/clips`](https://monsterapi.co/docs/api/twitch-clip#channel-clips): `clips[].slug`                           | [GET `/twitch/api/clip/{slug}`](https://monsterapi.co/docs/api/twitch-clip#clip-metadata)          |
| Collection ID | [GET `/twitch/api/channel/{login}/collections`](https://monsterapi.co/docs/api/twitch-video#channel-video-shelves): `shelves[].collection_id` | [GET `/twitch/api/collection/{id}`](https://monsterapi.co/docs/api/twitch-video#collection-videos) |
| Team slug     | [GET `/twitch/api/channel/{login}/recommended`](https://monsterapi.co/docs/api/twitch-channel#recommended-channels): `team.slug`              | [GET `/twitch/api/team/{name}`](https://monsterapi.co/docs/api/twitch-channel#twitch-team)         |

Category slugs also appear in `categories.items[].slug` from
[GET `/twitch/api/search`](https://monsterapi.co/docs/api/twitch-directory#search-channels-categories-and-recordings).

## Continue a listing

For [GET `/twitch/api/streams`](https://monsterapi.co/docs/api/twitch-directory#popular-live-streams), copy the top-level `next_cursor` unchanged into its `cursor` query parameter.
Keep the same filters. Set `NEXT_CURSOR` to that value for the next request:

```bash
curl -sS --get 'https://api.monsterapi.co/twitch/api/streams' \
  -H "Authorization: Bearer ${MONSTERAPI_KEY}" \
  --data-urlencode 'limit=3' \
  --data-urlencode "cursor=${NEXT_CURSOR}"
```

Records may repeat within or across pages. Keep the returned order.
Stop when `next_cursor` is absent or the endpoint returns `404` `not_found`.
An empty page with `next_cursor` returns `200`; continue with that cursor.

For [GET `/twitch/api/video/{id}/chat`](https://monsterapi.co/docs/api/twitch-video#recorded-chat), `offset` seeks to a window around a position in seconds.
That window may include earlier messages. Use `next_cursor` as `cursor` for sequential continuation; `cursor` takes precedence over `offset`.

## Get playback

For a live channel, request [GET `/twitch/api/stream/{login}/playback/token`](https://monsterapi.co/docs/api/twitch-video#live-playback-token),
then [GET `/twitch/api/stream/{login}/playback`](https://monsterapi.co/docs/api/twitch-video#live-hls-manifest).
For a recording, request [GET `/twitch/api/video/{id}/playback/token`](https://monsterapi.co/docs/api/twitch-video#recording-playback-token),
then [GET `/twitch/api/video/{id}/playback`](https://monsterapi.co/docs/api/twitch-video#recording-hls-manifest).

HLS responses can include an optional `other` list of additional nodes.
Each node has `type` and attributes with their original names and string values.
`BROADCAST-ID` identifies the live broadcast; `STREAM-TIME` is elapsed time in seconds, supplied as a string.
Playback variants and media tracks appear alongside this information.

Read `token` and `signature` at the top level of the token response.
Pass them unchanged as the `token` and `sig` query parameters for the same channel or recording. URL-encode both values.
If permission expires, playback returns `400` `bad_request`; request a new token.
An offline channel returns `404` `not_found` on playback, including after a token was issued.

## Handle errors and credits

Check the current operation price in the [API reference](https://monsterapi.co/docs/api). Under `http-status-v1`, endpoint responses with `2xx` or `4xx` are charged; `5xx` responses are refunded.

- `400` `bad_request`: correct the request parameters before retrying.
- `403` `private`: the resource isn’t available anonymously.
- `404` `not_found`: the resource is absent or the listing has ended.
- `500` `upstream_shape`: the answer couldn’t be read; this doesn’t mark the end of a listing.
- `501` `requires_auth`: the requested information isn’t available anonymously. [GET `/twitch/api/channel/{login}/mods`](https://monsterapi.co/docs/api/twitch-channel#moderator-roster) returns this code.
- `503`: access is temporarily unavailable. For `rate_limited` or `upstream_error`, wait the seconds named by `Retry-After` before retrying.

See [Errors](https://monsterapi.co/docs/errors) for the error envelope and gateway rejections, and [Pricing](https://monsterapi.co/docs/pricing) for billing rules.

## Public examples

Use the [API reference](https://monsterapi.co/docs/api) for ready-made public inputs and response examples.
Read [Examples](https://monsterapi.co/docs/examples) for provenance, preparation costs, task recipes, and pagination stop rules.