Get Videos

Learn to retrieve information regarding videos on Twitch.

We'll cover the following

Streamers can choose to save their past live streams as videos on their profiles so viewers can rewatch the videos or catch up on any missed streams. There are thousands of videos across Twitch, spanning multiple creators and categories. We can send a GET request to the videos endpoint of the Twitch API and retrieve the information of any video we want.

The URL for this endpoint is as follows:

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

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

Input parameters

There are three required query parameters and several other optional query parameters. A few combinations of these parameters are invalid. The table below gives an overview of each parameter and the accepted combinations:

Parameter

Type

Category

Description

id

String

Required

This is the ID of the video. If we provide this parameter, it doesn’t need any additional parameter, including user_id and game_id. We can provide a maximum of 100 video IDs.

user_id

String

Required

This is the ID of the user whose videos we want to fetch. We can only provide one user ID.

game_id

String

Required

This is the ID of the game whose videos we want to fetch. We can only provide one game ID.

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. It can only be provided if user_id or game_id is used, but not with id.

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 value in the before parameter to return the page of results after the page specified by the cursor. It can only be provided if user_id or game_id is used, but not with id.

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.

language

String

Optional

This is an ISO-639-1 two-letter code of the language the video is in.

period

String

Optional

This is the period within which the video was created. Its accepted values are "all", "day", "week", and "month". Its default value is "all".

sort

String

Optional

This is the order in which the returned videos are to be sorted. Its accepted values are "time", "trending", and "views". Its default value is "time".

type

String

Optional

This is the type of video. A video can be a reupload of a stream, a highlight of a stream, and so on. Its accepted values are "all", "upload", "archive", and "highlight". Its default value is "all".

Although all three ID parameters are listed as required parameters, we only need to provide one of them to make a successful request. In other words, we can choose to provide either the video ID, the user ID, or the game ID, but not more than one. It doesn’t require any other optional parameters if we choose to use the video ID—the id parameter.

Example calls

Let's make a couple of sample calls to this endpoint, using different combinations of the parameters. We can change the values of the parameters below or even add other parameters to the request.

Note: The code below extracts a video ID to be used later, so don't forget to save it. 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 = {
    'user_id'   : '12826',  # Official Twitch channel
    'sort'      : 'views'
}
response = requests.get('https://api.twitch.tv/helix/videos',
                        headers=headers, params=parameters).json()
print(json.dumps(response, indent=4))

The API responds with a list of videos the official Twitch channel has added to its profile. This list is sorted by the number of views.

Let's also make a request using a video ID. Here, we won't use any of the other optional parameters.

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

Since IDs are unique, we only get the details of the singular video we passed as a parameter.

Response structure

The JSON response has two top-level properties—data and pagination. The search results are contained in the data property in the form of an array of video objects. The table below discusses the properties of these objects:

Property

Type

Description

id

String

This is the ID of the video.

stream_id

String

This is the ID of the stream, if any, from which the video is taken. It has a value only if the type property is "archive". Otherwise, it is null.

user_id

String

This is the ID of the user to whom the video belongs.

user_login

String

This is the login name of the user to whom the video belongs.

user_name

String

This is the display name of the user to whom the video belongs.

title

String

This is the title of the video as it is displayed on the user's profile.

description

String

This is the description of the video.

created_at

String

This is an RFC3339 timestamp for when the video was created.

published_at

String

This is an RFC3339 timestamp for when the video was published.

url

String

This is the URL where the video can be accessed/viewed.

thumbnail_url

String

This is the static URL for the thumbnail of the video.

viewable

String

This is the viewing setting of the video—either "public" or "private".

view_count

Integer

This is the number of views the video has accumulated.

language

String

This is an ISO-639-1 code for the language the video is in.

type

String

This is the type of video that indicates whether the video is a reupload of a past stream, a new upload, and so on. This property can take any of these values—"upload", "archive", and "highlight".

duration

String

This is the running time of the video.

muted_segments

Object

This indicates which segments of the video, if any, are muted. This is an object containing two values, duration and offset. These define the duration of the muted segment and the offset from the beginning of the video where the muted segment begins.