Active Streams

Learn to retrieve a list of all ongoing streams on Twitch.

We'll cover the following

Most users visit Twitch to mainly watch live streams. In fact, the first page we see upon visiting Twitch contains a number of live streams. We can start watching them with just a click.

The Twitch API can also be used to get a similar list of streams. We can send a GET request to the streams endpoint of the Twitch API to get a list of all current live streams.

It returns a list sorted in descending order of current viewers, spread over multiple pages of results. Since we can fetch only one page at a time, subsequent requests for further pages might show duplicate or missing streams as viewers join and leave streams. This changes the order in which the streams are sorted.

The URL for this endpoint is as follows:

https://api.twitch.tv/helix/streams

All calls to this endpoint need to be authorized with either an app or a user access token. We'll use an app access token in this lesson.

Input parameters

It doesn’t require any parameters. However, we can provide several optional query parameters to filter the returned list of streams. These parameters are shown in the table below:

Parameter

Type

Category

Description

after

String

Optional

This is a cursor value for forward pagination. Each response from the streams endpoint that has multiple pages returns a cursor value. We can provide this value in the after parameter to return the page of results after the page specified by the cursor.

before

String

Optional

This is a cursor value for backward pagination. Each response from the streams endpoint that has multiple pages returns a cursor value. We can provide this value in the before parameter to return the page of results before the page specified by the cursor.

first

Integer

Optional

This is the number of streams to be returned per page, with a maximum of 100 results per page. Its default value is 20.

game_id

String

Optional

This parameter filters the returned streams based on the game specified by it. We can provide a maximum of 100 game IDs.

language

String

Optional

This is an ISO-639-1 code to filter results based on the stream language. We can provide a maximum of 100 language codes.

user_id

String

Optional

This parameter filters the returned streams based on the user ID specified by it. We can provide a maximum of 100 user IDs.

user_login

String

Optional

This parameter is similar to the user_id parameter. It filters the returned streams based on the user login name specified by this parameter. We can provide a maximum of 100 login names.

Example call

Let’s authorize ourselves with an app access token and make a request to this endpoint. We can then view the response we get from the API.

Note: If your token has expired, return to this lesson and follow the steps to generate a new one.

Press + to interact
headers = {
    'Authorization' : 'Bearer {{APP_ACCESS_TOKEN}}',
    'Client-Id'     : '{{CLIENT_ID}}'
}
response = requests.get('https://api.twitch.tv/helix/streams', headers=headers).json()
print(json.dumps(response, indent=4))

Response structure

A successful response to a call to this endpoint is a JSON object with two top-level properties—data and pagination. The data property is a list of stream objects and the pagination property contains a cursor value for pagination.

The table below gives an overview of the properties present in a single stream object contained within the data array:

Property

Type

Description

id

String

This is the ID of the stream.

user_id

String

This is the ID of the user broadcasting the stream.

user_login

String

This is the login name of the user broadcasting the stream.

user_name

String

This is the display name of the user broadcasting the stream.

game_id

String

This is the ID of the game being played on the stream.

game_name

String

This is the name of the game being played on the stream.

type

String

This is the type of stream. Since we're retrieving ongoing streams, its value is live. Its value is an empty string in case of an error.

title

String

This is the title of the stream.

viewer_count

Integer

This is the number of viewers currently watching the stream.

started_at

String

This is the UTC timestamp of when the stream was started.

language

String

This is an ISO-639-1 code for the stream language.

thumbnail_url

String

This is the URL of the stream thumbnail. We can retrieve different thumbnail sizes by replacing the {width} and {height} placeholders with the desired width and height values, respectively.

tag_ids

Array[String]

This is a list of IDs of all tags that apply to the stream.

is_mature

Boolean

This indicates whether the stream is intended for mature audiences.