Stream Schedules

Learn to fetch and create Twitch stream schedules.

We'll cover the following

To make it easier for viewers to tune in to their streams, streamers can set a streaming schedule on their channel that is public to all users. The schedule shows all the basic details of the stream. These include the stream’s title, its category, and its date and time.

Retrieving stream schedules

We can send a simple GET request to the schedules endpoint and fetch the stream schedule of any channel.

The URL for this endpoint is as follows:

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

All requests to this endpoint must be authenticated with either an app access token or a user access token. In this lesson, we'll use an app access token.

Request parameters

It requires a single query parameter, namely the ID of the streamer whose schedule we want. However, we can provide several optional parameters. The details of each parameter are discussed in the table below:

Parameter

Type

Category

Description

broadcaster_id

String

Required

This is the ID of the broadcaster whose stream schedule we want to fetch.

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.

first

Integer

Optional

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

id

String

Optional

This is the ID of the schedule segment to return. A segment is a single entry in a schedule.

start_time

String

Optional

This is an RFC3339 timestamp. If this value is specified, it returns only stream segments starting after the given time. It defaults to the current date and time.

utc_offset

String

Optional

This is the timezone offset from GMT measured in minutes. We can specify this to ensure that the results are returned for the correct week according to the timezone. Its default value is "0" for GMT.

Let's make a sample call to the schedules endpoint using some sample user IDs from the table below:

Channel Name

ID

TwitchDev

141981764

twitchgaming

527115020

TwitchRivals

197886470

Let's paste these user IDs into the broadcaster_id parameter on line 12.

Note: If your 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/schedule");
const headerParameters = {
  Authorization: "Bearer {{APP_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Specifying the broadcaster for which we want to fetch the stream schedule
const queryParameters = new URLSearchParams({
  broadcaster_id: "141981764",
});
const options = {
  method: "GET",
  headers: headerParameters,
};
async function fetchStreamSchedule() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
fetchStreamSchedule();

In the code above, we perform the following:

  • Lines 11–13: We define the query parameters for the request 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 fetchStreamSchedule to make a call to the schedules endpoint.

    • Lines 21–25: We make a call to the endpoint within a try block 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 fetchStreamSchedule function.

Response fields

The response JSON object consists of two properties—data containing the results and pagination containing a cursor value for pagination.

The data property is an object containing several other properties. The details of these properties are discussed in the table below:

Property

Type

Description

segments

Array[Object]

This is an array of stream segment objects.

broadcaster_id

String

This is the ID of the broadcaster to whose channel the schedule belongs.

broadcaster_name

String

This is the display name of the broadcaster to whose channel the schedule belongs.

broadcaster_login

String

This is the login name of the broadcaster to whose channel the schedule belongs.

vacation

Object

This is an object containing two properties—start_time and end_time. These specify the start and end times of the streamer's vacation period in RFC3339 format, if any.

The actual results are stored in the segments array embedded in the data object. Each element of this array is an object that represents a single schedule segment, where each segment represents an entry in the stream schedule. Schedule segments represent a stream that will be held in the future.

The table below gives an overview of the schedule segment object:

Property

Type

Description

id

String

This is the ID of the stream schedule segment.

start_time

String

This is an RFC3339 timestamp for the scheduled start time of the stream.

end_time

String

This is an RFC3339 timestamp for the scheduled end time of the stream.

title

String

This is the title of the scheduled stream.

canceled_until

String

This is an RFC3339 timestamp for the scheduled start time of the next stream if the stream is recurring and has canceled events. If neither of these conditions apply, this value is null.

category

Object

This is an object containing two properties—id and name. These represent the ID and name of the game the broadcaster will play on the stream.

is_recurring

Boolean

This determines whether or not the stream is a recurring event.

Schedule a stream

We can retrieve the schedules for different channels. Additionally, we can also schedule new streams using the Twitch API. Schedules for individual streams are known as segments. We can send a POST request to the schedule segments endpoint to create schedule segments for specified channels.

The URL for this endpoint is as follows:

https://api.twitch.tv/helix/schedule/segment

All calls to this endpoint must be authenticated with a user access token that has the channel:manage:schedule scope.

Request parameters

This endpoint requires a single query parameter and several body parameters. It also allows us to pass a few other optional body parameters. The table below gives an overview of all these parameters:

Parameter

Parameter Type

Type

Category

Description

broadcaster_id

Query

String

Required

This is the ID of the user for whom we want to update the schedule settings. It must be of the same user who is authenticated with the access token.

start_time

Body

String

Required

This is an RFC3339 timestamp for the starting time of the stream.

timezone

Body

String

Required

This is the timezone in the IANA time zone database format.

is_recurring

Body

Boolean

Required

This determines whether the stream is recurring.

duration

Body

Integer

Required

This is the duration of the stream in minutes.

category_id

Body

String

Optional

This is the ID of the game the streamer will play during the stream.

title

Body

String

Optional

This is the title of the stream. Its length cannot exceed 140 characters.

Let's make a sample call to this endpoint to schedule a recurring broadcast starting today. We can update the timezone and title parameters on lines 18 and 21, respectively.

Note: The code below extracts a segment ID to be used later, so don't forget to save it. 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/schedule/segment");
const headerParameters = {
  Authorization: "Bearer {{USER_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
  "Content-Type": "application/json",
};
const queryParameters = new URLSearchParams({
  broadcaster_id: "{{USER_ID}}",
});
// Defining the required body parameters
const bodyParameters = JSON.stringify({
  start_time: new Date().toISOString(),
  timezone: "America/New_York",
  is_recurring: true,
  duration: 120,
  title: "Testing the Twitch API",
});
const options = {
  method: "POST",
  headers: headerParameters,
  body: bodyParameters,
};
async function scheduleStream() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
scheduleStream();

In the code above, we perform the following:

  • Lines 5–9: We define the headers for the request, specifying the content type as application/json.

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

  • Lines 16–22: We define the body parameters for the request using the start_time, timezone, is_recurring, duration, and title parameters.

    • Line 17: We use the built-in Date object to generate a date string in ISO format.

  • Lines 24–28: We set the options for the API call, specifying the HTTP request type as POST and providing the request headers and body.

  • Lines 30–38: We define a function called scheduleStream to make a call to the schedule segments endpoint.

    • Lines 31–35: We make a call to the endpoint within a try block and print the response from the API.

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

  • Line 40: We invoke the scheduleStream function.

The response from this endpoint is almost identical to the response from the schedules endpoint except for the absence of the pagination property in the schedule segments endpoint’s response. Here, it returns the schedule for our channel, including the newly added schedule segment.