Twitch API Guide

Introduction

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.

Requests

Most of the API endpoints that are used to retrieve information use query parameters. In the case where multiple values can be provided, the parameter should be provided multiple times rather than comma-separated (e.g. &login=twitch&login=twitchdev&login=twitchgaming).

Data Models

With the Twitch API, our philosophy for responses is to remove extraneous data, return consistent structures, and simplify responses to a single layer. While simplifying the data models, we observed a lot of overlap between users and channels objects; as a result, we combined them into the user object.

Rate Limits

To prevent our API from being overwhelmed by too many requests, Twitch rate-limits requests. A token bucket algorithm is used, where a token (aka point) counts for a request. The refill rate is set on a steady-state rate and the burst is the maximum bucket size.

Each client ID has a point-refill rate of 800 points per minute per user and a bucket size of 800 points. The limit is across all Twitch API queries. If this limit is exceeded, an error is returned: HTTP 429 (Too Many Requests).

When you make an API request, you will receive a set of rate-limiting headers to help your application respond appropriately. The headers are:

• Ratelimit-Limit: The rate at which points are added to your bucket. This is the average number of requests per minute you can make over an extended period of time.
• Ratelimit-Remaining: The number of points you have left to use.
• Ratelimit-Reset: A Unix epoch timestamp of when your bucket is reset to full.

Individual endpoints may have additional rate limits, with additional headers to describe those limits. For details, see the documentation for each endpoint.

Individual endpoints are given a point value. When an endpoint is called, the point value of the endpoint is subtracted from the total points granted to your client ID. The default point value is 1; i.e., a point is equivalent to a request. Currently all endpoints have the same point value.

Real-time Information

Twitch API endpoints may have varying levels of caching depending on the type of information. EventSub should be considered for real-time information, which also alleviates the need to poll API endpoints for updated resulted.

Authentication

The Twitch API uses the Twitch authentication system, allowing the use of OAuth tokens for API requests. These tokens allow a developer to make API requests on behalf of your application or on behalf of a user.

Request headers will differ depending on whether a developer is using the Twitch API or Legacy Twitch API v5. See Sending User Access and App Access Tokens for more information.

For Extension developers, Twitch API requests from Extension front ends are supported using a JWT instead of the usual user or app access token. See Using the Twitch API in an Extension Front End for more information.

Service Unavailable Error

If you get an HTTP 503 (Service Unavailable) error, retry once. If that retry also results in an HTTP 503, there probably is something wrong with the downstream service. Check the status page for relevant updates.

Status Page

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