Contents

Twitch API Guide

The Twitch API provides the tools and data used to develop Twitch integrations. The data models and systems are designed to provide relevant data in an easy, consistent, and reliable way.

Specifying multiple query parameter values

Some endpoints use query parameters to filter the data. If a query parameter lets you specify a list of values, you must specify the query parameter for each value in the list; the list is not comma delimited. For example, to specify multiple login values, you’d specify them as &login=twitch&login=twitchdev&login=twitchgaming.

JSON deserialization

Because Twitch is constantly improving the API, which may include adding new fields to existing objects, you should use your JSON library’s ignore attribute to prevent the deserializer from generating an error when it encounters fields that your class doesn’t define.

For example, if you use Jackson, you can include @JsonIgnoreProperties(ignoreUnknown = true) on the class or set the global DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES configuration property to false.

Pagination

The Twitch API supports cursor-based pagination for APIs that return lists of resources.

List APIs use the following query parameters to control paging:

The after and before parameters are mutually exclusive; you may not specify both in the same call.

If a list API can return another page of results, the response contains a Pagination object that includes the cursor field.

    "pagination": {
      "cursor": "eyJiI..."
    }

When paging forward, the cursor marks the top of the next page of results. If the API supports paging backward, the cursor also marks the top of the previous page of results.

Use the cursor’s value to set the after or before query parameter depending on the direction you want to page. See Forward pagination and Backward pagination.

The Pagination object is empty if there are no more pages to return in the direction you’re paging.

    "pagination": {}

Specifying the page size

List requests return a default number of items per page. For example, by default, Get Streams returns a maximum of 20 items per page. To specify a different page size, use the first query parameter with each request.

curl -X GET 'https://api.twitch.tv/helix/streams?first=40' \ 
-H 'Authorization: Bearer <access token goes here>' \
-H 'Client-Id: <client id goes here>'

If an API supports pagination, its documentation specifies the default page size and the maximum page size that you may specify. For example, the maximum page size for Get Streams is 100.

A page may contain less than the number of items requested, which is often the case for the last page of results.

Forward pagination

To get the first page, don’t specify the after query parameter.

curl -X GET 'https://api.twitch.tv/helix/streams?first=40' \ 
-H 'Authorization: Bearer <access token goes here>' \
-H 'Client-Id: <client id goes here>'

To get the next page, and all subsequent pages, set the after query parameter to the value in the cursor field of the response’s Pagination object.

curl -X GET 'https://api.twitch.tv/helix/streams?first=40&after=eyJiI...' \ 
-H 'Authorization: Bearer <access token goes here>' \
-H 'Client-Id: <client id goes here>'

You know you’re at the end of the list when the response contains an empty Pagination object.

Backward pagination

Not all APIs support paging backward. Check the documentation to confirm whether the API supports backward pagination — the list of query parameters includes the before query parameter.

To page backward through a list, set the before query parameter to the value in the cursor field of the response’s Pagination object.

curl -X GET 'https://api.twitch.tv/helix/streams?first=40&before=eyJiI...' \ 
-H 'Authorization: Bearer <access token goes here>' \
-H 'Client-Id: <client id goes here>'

You know you’re at the beginning of the list when the response contains an empty Pagination object. To page forward when you’re at the top of the list, don’t include a cursor parameter.

If you page forward to the end of the list, the Pagination object is empty. Because of this, you must keep a copy of the previous cursor to use to page backward.

Lists are dynamic

Because lists are dynamic views of the data, it’s possible that the cursor may return an empty page ("data":[]) when you’re near the end of the list.

It’s also possible that the data that a user sees on one page could show up on the next or previous page. For example, Get Streams orders the list of streamers by their number of viewers. If the streamer’s viewership changes between the time you get the cursor and the the time the user pages forward or backward, it’s possible that the streamer could have moved up or down in the list and the user would see them twice.

For the same reason, it’s also possible that if the user pages forward and then backward, the contents of the previous page may be partially or fully different depending on how volatile the data is.

Known issues

The following list contains known issues that you should consider when designing your app.

  1. The Get EventSub Subscriptions endpoint doesn’t let you specify the page size (the first query parameter is not supported).
  2. The Get Extension Live Channels endpoint doesn’t use the same Pagination object as the other endpoints that support paging. Instead, it contains a pagination field that contains either an empty string or a cursor value.

Rate limits

To protect our services, and to make sure there are enough resources for all our partners, Twitch limits the number of requests a client ID (app) may make. If your app exceeds the limit, the request returns HTTP status code 429 (Too Many Requests).

How it works

Twitch uses a token-bucket algorithm to ensure the limits are respected. Your app is given a bucket of points. Each endpoint is assigned a points value (the default points value per request for an endpoint is 1). When your app calls the endpoint, the endpoint’s points value is subtracted from the remaining points in your bucket. If your bucket runs out of points within 1 minute, the request returns status code 429.

Your app is given a bucket for app access requests and a bucket for user access requests. For requests that specify a user access token, the limits are applied per client ID per user per minute.

If an endpoint uses a non-default points value, or specifies different limit values, the endpoint’s documentation identifies the differences.

For details about the Extensions API rate limits, see Extension rate limits.

Keeping track of your usage

The API includes the following headers with each response to help you stay within your request limits.

If you receive HTTP status code 429, use the Ratelimit-Reset header to learn how long you must wait before making another request.

Real-time information

Given the choice between polling an endpoint for updates or subscribing to an update event, choose events. See EventSub subscriptions.

Authentication

Twitch supports the following authentication schemes.

  1. OAuth 2.0 — See Getting OAuth tokens.
  2. OpenID Connect (JSON Web Token) — See Getting OIDC tokens.

For an overview of using authentication in the Twitch API, see Authentication.

For information about JSON Web Tokens (JWT), see JSON Web Tokens.

For Extension developers, the Extensions API supports only JWTs. The following topics contain relevant JWT information.

Service unavailable error

If you get an HTTP status code 503 (Service Unavailable) error, retry once. If the retry also returns 503, check the status page for relevant updates. You may also report any issue that appears to be a bug via GitHub Issues.

Status page

The Twitch API has a public status page that contains aggregate information about service health and incidents. You can subscribe to this page to receive automated alerts.

Docs Status Support Showcase Blog