Followed Streams

Learn to get all the active streams from the 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 the 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.

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

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
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/streams/followed");
const headerParameters = {
  Authorization: "Bearer {{USER_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
const queryParameters = new URLSearchParams({
  user_id: "{{USER_ID}}",
});
const options = {
  method: "GET",
  headers: headerParameters,
};
async function fetchFollowedStreams() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
fetchFollowedStreams();

In the code above, we perform the following:

  • Lines 10–12: We define the query parameters for the request using the user_id parameter.

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

  • Lines 19–27: We define a function called fetchFollowedStreams to make a call to the followed streams endpoint.

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

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

  • Line 29: We invoke the fetchFollowedStreams function.

The returned list will be empty if none of the channels we're following are currently live. We can try following a few live channels and rerunning the code. The response will then include the active streams of every user we follow.

Response fields

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