Follows and Subscriptions

Learn to retrieve information about followers and subscribers 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 both provide slightly different forms of support.

In the case of follow, when a user follows another user, Twitch notifies the former when the latter goes live. Moreover, it's free to follow another user on Twitch.

In comparison, users financially support streamers through monthly donations when they subscribe to them. Additionally, the subscribers receive exclusive perks as a reward for subscribing to the streamer.

Follows

Let's start by looking at the first of these cases. We can send a GET request to the user 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.

Request 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.

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
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/users/follows");
const headerParameters = {
  Authorization: "Bearer {{APP_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Defining the user for which we want to fetch followed users/channels
const queryParameters = new URLSearchParams({
  from_id: "{{USER_ID}}",
});
const options = {
  method: "GET",
  headers: headerParameters,
};
async function getFollowedChannels() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
getFollowedChannels();

In the code above, we perform the following:

  • Lines 11–13: We define the query parameters for the call using the from_id parameter.

  • Lines 15–18: We set the options for the API call, specifying the HTTP request type as GET and providing the request headers.

  • Lines 20–28: We define a function called getFollowedChannels to make a call to the user follows endpoint.

    • Lines 21–25: Within a try block, we provide the query parameters, make a call to the endpoint, and print the response from the API.

    • Lines 25–27: We catch any errors or exceptions within a catch block and print them to the console.

  • Line 30: We invoke the getFollowedChannels function.

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 rerunning the code. It will then include everyone we've followed so far. We can also try replacing the ID on line 12 with other user IDs.

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

Press + to interact
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/users/follows");
const headerParameters = {
  Authorization: "Bearer {{APP_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Defining the user for which we want to fetch the list of followers
const queryParameters = new URLSearchParams({
  to_id: "{{USER_ID}}",
});
const options = {
  method: "GET",
  headers: headerParameters,
};
async function getFollowers() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
getFollowers();

In the code above, we perform the following:

  • Lines 11–13: We define the query parameters for the call, this time using the to_id parameter.

  • Lines 15–18: We set the options for the API call, specifying the HTTP request type as GET and providing the request headers.

  • Lines 20–28: We define a function called getFollowers to make a call to the user follows endpoint.

    • Lines 21–25: Within a try block, we provide the query parameters, make a call to the endpoint, and print the response from the API.

    • Lines 25–27: We catch any errors or exceptions within a catch block and print them to the console.

  • Line 30: We invoke the getFollowers function.

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

Response fields

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, which 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.

Request 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 as the one 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.

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
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/subscriptions");
const headerParameters = {
  Authorization: "Bearer {{USER_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Defining the user for whom we want to fetch the list of followers
const queryParameters = new URLSearchParams({
  broadcaster_id: "{{USER_ID}}",
});
const options = {
  method: "GET",
  headers: headerParameters,
};
async function getSubscribers() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
getSubscribers();

In the code above, we perform the following:

  • Lines 11–13: We define the query parameters for the call using the broadcaster_id parameter.

  • Lines 15–18: We set the options for the API call, specifying the HTTP request type as GET and providing the request headers.

  • Lines 20–28: We define a function called getSubscribers to make a call to the subscriptions endpoint.

    • Lines 21–25: Within a try block, we provide the query parameters, make a call to the endpoint, and print the response from the API.

    • Lines 25–27: We catch any errors or exceptions within a catch block and print them to the console.

  • Line 30: We invoke the getSubscribers function.

Note: If no users have subscribed to our channel, the response fields will be empty.

Response fields

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 user 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 objects:

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.