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:

• after — Use to get the next page of results
• before — Use to get the previous page of results
• first — Use to specify the page size

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.

• Ratelimit-Limit — The rate at which points are added to your bucket.
• Ratelimit-Remaining — The number of points in your bucket.
• Ratelimit-Reset — A Unix epoch timestamp that identifies when your bucket is reset to full.

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.

• Creating Your Extension Backend Service (EBS)
• Managing Extension Secrets
• Using the Twitch API in an Extension Front End

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.

Breaking changes

In rare cases it may be necessary to introduce breaking changes to the Twitch API. Twitch will provide as much notification as possible prior to introducing a breaking change; however, there may be times when providing prior notification isn’t possible (for example, to address security or privacy issues).

Twitch uses the Announcement section of the Twitch Developer Forum to provide notification of a pending breaking change. To prevent disruption of your application or service, be sure to update your application as appropriate and in a timely fashion. The notification will identify all programming elements involved in the breaking change and will provide guidance on work-arounds if available.

Some of the reasons why Twitch may introduce a breaking change, include but are not limited to:

• Security issues
• Privacy concerns
• Legal concerns
• A bug that prevents the API from working as intended (for example, adding or updating constraints, adding required parameters without default values, or changing the response data)
• A business change that requires removal of an API or feature of an API such as removing an option to retrieve a single resource instead of the entire list

Non-breaking changes

Twitch may make the following non-breaking changes without prior notification:

• Add optional query parameters or fields to a request
• Add new values to the list of possible values that you can set the request’s query parameters or fields to
• Add fields to the response (your code should ignore any fields that it doesn’t expect)
• Change the order of the fields in the response
• Add or update error message strings (your code should not take dependencies on message strings)
• Change the path, query parameters, or fragment of a URL that the API returns such as image URLs (your code should not take dependencies on the URLs that the API returns except where noted)

To discover non-breaking changes, review the change log.

Taking dependencies

Your application should not take dependencies on:

• Error message strings
• URLs that the API returns (except where noted)
• The format of strings in the API responses