Twitch API Guide
Starting on April 30, 2020, all Helix endpoints will require OAuth and matching client IDs. See this announcement for more details. Documentation will be updated as these requirements go into effect.
Introduction
The new Twitch API provides the tools and data used to develop integrations with Twitch. The data models and systems are designed to provide relevant data in an easy, consistent, and reliable way.
Requests
API endpoint support for JSONP has been removed.
Request parameters are &-repeated (e.g., &login=&login=&login=), not comma-separated as in Twitch API v5.
Data Models
With the new Twitch API, we revisited all our data models. Our philosophy for responses was to remove extraneous data, return consistent structures, and simplify responses to a single layer. This removes the deeply-nested structures of the prior API, provides faster response times, and provides flexibility for optimizing API calls. 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 bucketalgorithm 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 and bucket size which depend on whether a bearer token is provided:
| Authentication | Refill Rate | Bucket Size |
|---|---|---|
| Bearer token is provided | 800 points per minute, per user | 800 points |
| Bearer token is not provided | 30 points per minute | 30 points |
The limit is across all New 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. (All New Twitch API endpoints have the default point value. In the future, if an endpoint has a higher point value, that will be covered in the reference documentation for the endpoint.)
If you need a higher rate limit, please fill out the form at https://dev.twitch.tv/limit-increase.
Webhooks
The new Twitch API includes a webhook system that allows you to subscribe to a topic and be notified when new data comes in for that topic. This helps to alleviate the need to poll the API for fresh data. With each release, we add more topics.
Authentication
The new Twitch API uses the existing Twitch authentication system, and it allows the use of application tokens for API calls. These application tokens allow you to make an API request on behalf of your application rather than on behalf of a user.
The header differs, depending on whether you use the new Twitch API or Twitch API v5. See Sending User Access and App Access Tokens (in the Apps & Authentication Guide).
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 new Twitch API has a public status page. You will find aggregate information about service health and incidents. You can subscribe to this page, to get automated alerts around this data.