Follows and Subscriptions

Learn to retrieve information about user follows and subscriptions on Twitch.

We'll cover the following

On most social media platforms, the terms follow and subscribe usually mean something similar. That’s not the case on Twitch. Both terms describe ways of supporting other broadcasters but are slightly different forms of support.

When a user follows another on Twitch, they’re notified when the followed user goes live. Following another user is also completely free. However, through subscriptions, users can provide financial support to streamers through monthly donations. Additionally, the subscribers also receive exclusive perks as an incentive.

Follows

Let's start by looking into the first of these cases. We can send a GET request to the users follows endpoint to fetch information regarding who's following who.

The URL for this endpoint is as follows:

https://api.twitch.tv/helix/users/follows

All calls to this endpoint need to be authorized with an app access token.

Input parameters

This endpoint takes some optional parameters. Their details are discussed in the table below:

Parameter

Type

Category

Description

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 value in the after parameter to return the page of results after the page specified by the cursor.

first

Integer

Optional

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

from_id

String

Optional

This is the ID of the user for which we want to retrieve the list of followed channels.

to_id

String

Optional

This is the ID of the user for which we want to retrieve the list of following users.

Although these are optional parameters, either from_id or to_id must be provided. Otherwise, the query results in an error.

Sample calls

Let's try making a couple of requests to this endpoint using the different parameters, starting with the from_id parameter.

Note: If your app access 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}}'
}
parameters = {
    'from_id' : '{{USER_ID}}'
}
response = requests.get('https://api.twitch.tv/helix/users/follows',
                        headers=headers, params=parameters).json()
print(json.dumps(response, indent=4))

In this example, we pass our own ID in the from_id parameter. This allows us to retrieve the list of all the channels we’ve followed.

The returned list will be empty if we haven't followed any channel yet. We can try following a few streamers and rerun the code. It will then include everyone we’ve followed so far. We can also try replacing the ID on line 7 with other user IDs.

Let's also try using the to_id parameter in the code below:

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

Here, the response lists every user following our channel. Try replacing the ID on line 7 to fetch the follower list for other channels.

Response structure

A successful response to a call for this endpoint is in the form of a JSON object with three top-level properties—total, data, and pagination.

  • total: This is the total number of returned results.
  • data: This is an array of objects, with each object representing a user follow. The complete details of the user follows object are discussed in the table below.
  • pagination: This is an object containing a single property, cursor, that represents the starting point of the returned results. This cursor value can be used for forward or backward pagination using the after and before input query parameters of subsequent requests.

The table below discusses the details of the user follows object:

Property

Type

Description

from_id

String

This is the follower's ID.

from_login

String

This is the follower's login name.

from_name

String

This is the follower's display name.

to_id

String

This is the ID of the streamer the user is following.

to_login

String

This is the login name of the streamer the user is following.

to_name

String

This is the display name of the streamer the user is following.

followed_at

String

This is the UTC timestamp of when the from_id user followed the to_id user.

Subscriptions

Let's move on to subscriptions now. We can send a GET request to the subscriptions endpoint to retrieve a list of all users that are subscribed to a channel.

The URL for this endpoint is as follows:

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

All requests must be authenticated with a user access token that has the channel:read:subscriptions scope.

Input parameters

This endpoint takes a single required parameter with some optional parameters shown in the table:

Parameter

Type

Category

Description

broadcaster_id

String

Required

This is the ID of the user for whom we want to retrieve the list of subscribers. 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 value in the after parameter to return the page of results after the page specified by the cursor.

first

Integer

Optional

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

user_id

String

Optional

This is the ID of a subscriber. It’s used to filter the returned list. We can provide a maximum of 100 IDs.

Sample call

Let's try making a sample request to this endpoint.

Note: If your user access 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 = {
    'broadcaster_id' : '{{USER_ID}}'
}
response = requests.get('https://api.twitch.tv/helix/subscriptions',
                        headers=headers, params=parameters).json()
print(json.dumps(response, indent=4))

Response structure

A successful JSON response from this endpoint contains four top-level properties—data, pagination, points, and total. The only new property here is points. The other three were included in the response for the users follows endpoint as well. This property shows the total number of subscriber points the channel has accumulated. Points are earned when a user subscribes with different points for different subscription tiers.

The actual results are stored in the data property in the form of an array of subscription objects. The table below discusses the details of the subscription object:

Property

Type

Description

broadcaster_id

String

This is the ID of the channel that the user is subscribed to.

broadcaster_login

String

This is the login name of the channel that the user is subscribed to.

broadcaster_name

String

This is the display name of the channel that the user is subscribed to.

gifter_id

String

This is the ID of the user that gifted the subscription. If the subscription was not gifted, this is an empty string—"".

gifter_login

String

This is the login name of the user that gifted the subscription. If the subscription was not gifted, this is an empty string—"".

gifter_name

String

This is the display name of the user that gifted the subscription. If the subscription was not gifted, this is an empty string—"".

is_gift

Boolean

This indicates whether the subscription was gifted to the subscribed user.

tier

String

This is the subscription tier. There are three tiers: Tier 1, Tier 2, and Tier 3.

plan_name

String

This is the name of the subscription.

user_id

String

This is the ID of the subscribed user.

user_name

String

This is the display name of the subscribed user.

user_login

String

This is the login name of the subscribed user.