Get Clips
Learn to retrieve information regarding clips on Twitch.
We'll cover the following
On the surface, videos and clips might sound like the same thing. However, they’re different forms of content on Twitch. Videos are created by streamers to be displayed on their profiles. They may be reuploads of a past stream, trailers for their channels, and so on.
On the other hand, clips are short, 30-second snippets, created by viewers from a streamer’s live stream or a previously uploaded video. These clips are displayed on the streamer’s profile and are sorted by the number of views.
Get clip information
We can send a GET request to the clips endpoint of the Twitch API and fetch the details of a clip.
The URL for this endpoint is as follows:
https://api.twitch.tv/helix/clips
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
It requires three 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 |
| String | Required | This is the ID of the clip. If we provide this parameter, it doesn’t need any other additional parameter, including |
| String | Required | This is the ID of the user whose clips we want to fetch. We can only provide one user ID. |
| String | Required | This is the ID of the game whose clips we want to fetch. We can only provide one game ID. |
| 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 |
| 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 |
| 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 |
| String | Optional | This is an RFC3339 timestamp to filter returned clips after a specified time. If we specify this, we must also specify |
| String | Optional | This is an RFC3339 timestamp to filter returned clips before a specified time. If we specify this, we must also specify |
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 clip ID, the broadcaster ID, or the game ID, but not more than one. It doesn’t require any other optional parameters if we choose to use the clip ID.
Example call
Let's make a sample call to this endpoint using the broadcaster_id
parameter. We can change the values of the parameters below or even add other parameters to the request.
Note: If your access token has expired, return to this lesson and follow the steps to generate a new one.
headers = {'Authorization' : 'Bearer {{APP_ACCESS_TOKEN}}','Client-Id' : '{{CLIENT_ID}}'}parameters = {'broadcaster_id' : '12826' # Official Twitch channel}response = requests.get('https://api.twitch.tv/helix/clips',headers=headers, params=parameters).json()print(json.dumps(response, indent=4))
The API responds with a list of clips the viewers have created from videos or streams that the official Twitch channel has uploaded. This list is sorted by the number of views.
Response structure
The JSON response has two top-level properties—data
and pagination
. The data
property contains the search results in the form of an array of clip objects. The table below discusses the properties of these objects:
Property | Type | Description |
| String | This is the ID of the clip. |
| String | This is the URL where the clip can be accessed/viewed. |
| String | This is the embed URL of the clip. |
| String | This is the ID of the broadcaster who owns the original video or stream that was clipped. |
| String | This is the display name of the broadcaster who owns the original video or stream that was clipped. |
| String | This is the ID of the user who created the clip. |
| String | This is the display name of the user who created the clip. |
| String | This is the ID of the original video that was clipped. |
| String | This is the ID of the game that is being played in the clip. |
| String | This is an ISO-639-1 code for the language the video is in. |
| String | This is the title of the clip. |
| Integer | This is the number of views the clip has accumulated. |
| String | This is an RFC3339 timestamp for when the clip was created. |
| String | This is the static URL for the thumbnail of the clip. |
| Float | This is the running time of the clip. |