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.

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

Example call

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

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

Response structure

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 none of these 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.

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

Example call

Let's make a sample call to this endpoint to schedule a recurring broadcast starting from 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
# Importing the datetime library to access date/time functions
from datetime import datetime, timedelta
headers = {
    'Authorization' : 'Bearer {{USER_ACCESS_TOKEN}}',
    'Client-Id'     : '{{CLIENT_ID}}'
}
parameters = {
    'broadcaster_id' : '{{USER_ID}}',
}
# Getting the current date/time for the start date
start = datetime.now()
payload = {
    'start_time'    : start.astimezone().isoformat(),
    'timezone'      : 'America/New_York',
    'is_recurring'  : True,
    'duration'      : 120,
    'title'         : 'Testing the API'
}
response = requests.post('https://api.twitch.tv/helix/schedule/segment',
                         headers=headers, params=parameters, json=payload).json()
print(json.dumps(response, indent=4))

The response from this endpoint is identical to the response from the schedules endpoint with the absence of the pagination property. Here, it returns the schedule for our channel, including the newly added schedule segment.