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.

Request 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

id

String

Required

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

broadcaster_id

String

Required

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

game_id

String

Required

This is the ID of the game whose clips 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 broadcaster_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 broadcaster_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.

started_at

String

Optional

This is an RFC3339 timestamp to filter returned clips after a specified time. If we specify this, we must also specify ended_at.

ended_at

String

Optional

This is an RFC3339 timestamp to filter returned clips before a specified time. If we specify this, we must also specify started_at.

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. We don’t need to provide any other optional parameters if we use the clip ID.

Let's make a sample call to this endpoint using the broadcaster_id parameter. We can change the values of the parameters below or 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.

Press + to interact
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/clips");
const headerParameters = {
  Authorization: "Bearer {{APP_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Providing only the id parameter
const queryParameters = new URLSearchParams({
  broadcaster_id: "12826",    // Official Twitch channel
});
const options = {
  method: "GET",
  headers: headerParameters,
};
async function getClipDetails() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
getClipDetails();

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 getClipDetails to make a call to the clips 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 getClipDetails function.

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 fields

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

id

String

This is the ID of the clip.

url

String

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

embed_url

String

This is the embedded URL of the clip.

broadcaster_id

String

This is the ID of the broadcaster who owns the original video or stream that was clipped.

broadcaster_name

String

This is the display name of the broadcaster who owns the original video or stream that was clipped.

creator_id

String

This is the ID of the user who created the clip.

creator_name

String

This is the display name of the user who created the clip.

video_id

String

This is the ID of the original video that was clipped.

game_id

String

This is the ID of the game that is being played in the clip.

language

String

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

title

String

This is the title of the clip.

view_count

Integer

This is the number of views the clip has accumulated.

created_at

String

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

thumbnail_url

String

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

duration

Float

This is the running time of the clip.