Followed Streams

Learn to get all active streams from followed channels.

We'll cover the following

Get followed streams

While the streams endpoint gets us a list of all the currently active live streams, what if we only want to see streams from the channels we follow? In that case, we can use the Twitch API's followed streams endpoint. We can send a GET request to this endpoint and receive a list of all active streams of the channels we follow. It returns a list, sorted in descending order of viewers, split over multiple pages.

The URL for this endpoint is as follows:

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

All calls to this endpoint need to be authorized with a user access token that has the user:read:follows scope. The response includes a list of all the streams from the channels the user authenticated with the access token follows.

Input parameters

This endpoint takes a single required query parameter and three optional parameters. The table below gives a summary of all these parameters:

Parameter

Type

Category

Description

user_id

String

Required

This is the user ID for which we want to retrieve the list of followed streams. It must be of the same user authenticated with the access token.

after

String

Optional

This is a cursor value for forward pagination. Each response from this endpoint that has multiple pages returns a cursor value. We can provide this cursor 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 this endpoint that has multiple pages returns a cursor value. We can provide this cursor 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 also 100.

Example call

Let's make a sample request to this endpoint and view the response.

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 {{USER_ACCESS_TOKEN}}',
    'Client-Id'     : '{{CLIENT_ID}}'
}
parameters = {
    'user_id' : '{{USER_ID}}'
}
response = requests.get('https://api.twitch.tv/helix/streams/followed',
                        headers=headers, params=parameters).json()
print(json.dumps(response, indent=4))

Response structure

The response is a JSON object containing 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.