New Twitch API Guide

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

Each client ID is granted a total of 30 queries per minute (if a Bearer token is not provided) or 120 queries per minute (if a Bearer token is provided), 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 number of requests you can use for the rate-limit window.
  • RateLimit-Remaining — The number of requests you have left to use for the rate-limit window.
  • RateLimit-Reset — A Unix epoch timestamp of when your rate-limit window will reset.

Individual endpoints may have additional rate limits, with additional headers to describe those limits. For details, see the documentation for each 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 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.