Videos - API Reference | Twitch Developers

Get Videos

You may get videos by ID, by user, or by game/category.

You must specify exactly one of the id, user_id and game_id query parameters; the request fails if you specify none of them or more than one.

You may apply several filters to get a subset of the videos. The filters are applied as an AND operation to each video. For example, if language is set to 'de' and game_id is set to 21779, the response includes only videos that show playing League of Legends by users that stream in German. The filters apply only if you get videos by user ID or game ID.

Endpoint

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

Authorization

Requires one of the following:

A user access token.
An app access token.

Query Parameters

idString
A list of IDs that identify the videos you want to get. To get more than one video, include this parameter for each video you want to get. For example, 'id=1234&id=5678'. You may specify a maximum of 100 IDs. The endpoint ignores duplicate IDs and IDs that weren't found.

The id, user_id, and game_id parameters are mutually exclusive.
user_idString
The ID of the user whose list of videos you want to get. The id, user_id, and game_id parameters are mutually exclusive.
game_idString
A category or game ID. The response contains a maximum of 500 videos that show this content. To get category/game IDs, use the Search Categories endpoint.

The id, user_id, and game_id parameters are mutually exclusive.
languageString
A filter used to filter the list of videos by the language that the video owner broadcasts in. For example, to get videos that were broadcast in German, set this parameter to the ISO 639-1 two-letter code for German (i.e., DE). For a list of supported languages, see Supported Stream Language. If the language is not supported, use "other." To filter by more than one language, separate the codes with commas (for example, de,en).

Specify this parameter only if you specify the game_id or user_id query parameter. If you specify game_id but not language, the API filters by the first language in the request's Accept-Language header, if the request includes one.
periodString
A filter used to filter the list of videos by when they were created. For example, videos created in the last week. The default is all.
Possible values
- all
- day
- month
- week
sortString
The order to sort the returned videos in. The default is time.
Possible values
- time
  Sort the results in descending order by when they were created (i.e., latest video first). If you specify user_id, the API sorts by when the videos were published, or by when they were created if they weren't published.
- trending
  Sort the results in descending order by biggest gains in viewership (i.e., highest trending video first).
- views
  Sort the results in descending order by most views (i.e., highest number of views first).
typeString
A filter used to filter the list of videos by the video's type. The default is all.
Possible values
- all
- archive
  On-demand videos (VODs) of past streams.
- highlight
  Highlight reels of past streams.
- upload
  External videos that the broadcaster uploaded using the Video Producer.
firstInteger
The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100. The default is 20.

Specify this parameter only if you specify the game_id or user_id query parameter.
afterString
The cursor used to get the next page of results. The Pagination object in the response contains the cursor's value. Read More

Specify this parameter only if you specify the game_id or user_id query parameter.
beforeString
The cursor used to get the previous page of results. The Pagination object in the response contains the cursor's value. Read More

Specify this parameter only if you specify the game_id or user_id query parameter.

Response Body

dataObject[]
The list of published videos that match the filter criteria. The list is always empty if the request comes from a region where videos aren't available.
Hide child attributesShow child attributes
- data.idString
  An ID that identifies the video.
- data.stream_idString
  The ID of the stream that the video originated from if the video's type is "archive;" otherwise, null.
- data.user_idString
  The ID of the broadcaster that owns the video.
- data.user_loginString
  The broadcaster's login name.
- data.user_nameString
  The broadcaster's display name.
- data.titleString
  The video's title.
- data.descriptionString
  The video's description.
- data.created_atString
  The date and time, in UTC, of when the video was created. The timestamp is in RFC3339 format.
- data.published_atStringNullable
  The date and time, in UTC, of when the video was published. The timestamp is in RFC3339 format.
- data.urlString
  The video's URL.
- data.thumbnail_urlString
  A URL to a thumbnail image of the video. Before using the URL, you must replace the '%{width}' and '%{height}' placeholders with the width and height of the thumbnail you want returned. Due to current limitations, '${width}' must be 320 and '${height}' must be 180.
- data.viewableString
  The video's viewable state. Always set to public.
- data.view_countInteger
  The number of times that users have watched the video.
- data.languageString
  The ISO 639-1 two-letter language code that the video was broadcast in. For example, the language code is DE if the video was broadcast in German. For a list of supported languages, see Supported Stream Language. The language value is "other" if the video was broadcast in a language not in the list of supported languages.
- data.typeString
  The video's type.
  Possible values
  - archive
    An on-demand video (VOD) of one of the broadcaster's past streams.
  - highlight
    A highlight reel of one of the broadcaster's past streams. See Creating Highlights.
  - upload
    A video that the broadcaster uploaded to their video library. See Upload under Video Producer.
  - past_premiere
    A past Premiere. Returned only when you get videos by id.
  - premiere_upload
    A video uploaded for a Premiere. Returned only when you get videos by id.
- data.durationString
  The video's length in hours (h), minutes (m), and seconds (s), with leading zero units left out. For example, 3m21s represents 3 minutes, 21 seconds, and 1h0m5s represents 1 hour, 5 seconds.
- data.muted_segmentsObject[]Nullable
  The segments that Twitch Audio Recognition muted; otherwise, null. Always null if you use an app access token.
  Hide child attributesShow child attributes
  - data.muted_segments.durationInteger
    The duration of the muted segment, in seconds.
  - data.muted_segments.offsetInteger
    The offset, in seconds, from the beginning of the video to where the muted segment begins.
paginationObject
Contains the information used to page through the list of results. The object is empty if the page has no videos, if you get videos by id, or if you specify game_id and reach the 500-video limit. The last page of results may still include a cursor; the page after it is empty. Read More
Hide child attributesShow child attributes
- pagination.cursorString
  The cursor used to get the next page of results. Use the cursor to set the request's after or before query parameter depending on whether you're paging forwards or backwards through the results.

Response Codes

200OK: Successfully retrieved the list of videos.
400Bad Request: The request must specify either the id or user_id or game_id query parameter.
The id, user_id, and game_id query parameters are mutually exclusive; you must specify only one of them.
The value in the id query parameter is not valid.
The ID in the game_id query parameter is not valid.
The value in the type query parameter is not valid.
The value in the period query parameter is not valid.
The value in the sort query parameter is not valid.
The ID in the user_id query parameter is not valid.
The first query parameter is outside the allowed range of values.
The cursor specified in the after or before query parameter is not valid.
The request may specify either the after or before query parameter but not both.
401Unauthorized: The Authorization header is required and must contain an app access token or user access token.
The access token is not valid.
The ID specified in the Client-Id header does not match the client ID specified in the access token.
404Not Found: The ID in the game_id query parameter was not found.
503Service Unavailable: The API couldn't get the videos. Try the request again.

Request Example

curl -X GET 'https://api.twitch.tv/helix/videos?id=335921245' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/videos?id=335921245" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/videos?id=335921245", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
  },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.twitch.tv/helix/videos",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    params={
        "id": "335921245",
    },
)

data = response.json()

req, _ := http.NewRequest("GET", "https://api.twitch.tv/helix/videos?id=335921245", nil)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/videos?id=335921245");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
]);

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.twitch.tv/helix/videos?id=335921245");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .get("https://api.twitch.tv/helix/videos?id=335921245")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

let data = response.text().await?;

Response Example

{
  "data": [
    {
      "id": "335921245",
      "stream_id": null,
      "user_id": "141981764",
      "user_login": "twitchdev",
      "user_name": "TwitchDev",
      "title": "Twitch Developers 101",
      "description": "Welcome to Twitch development! Here is a quick overview of our products and\ninformation to help you get started.",
      "created_at": "2018-11-14T21:30:18Z",
      "published_at": "2018-11-14T22:04:30Z",
      "url": "https://www.twitch.tv/videos/335921245",
      "thumbnail_url": "https://static-cdn.jtvnw.net/cf_vods/d2nvs31859zcd8/twitchdev/335921245/ce0f3a7f-57a3-4152-bc06-0c6610189fb3/thumb/index-0000000000-%{width}x%{height}.jpg",
      "viewable": "public",
      "view_count": 1863062,
      "language": "en",
      "type": "upload",
      "duration": "3m21s",
      "muted_segments": [
        {
          "duration": 30,
          "offset": 120
        }
      ]
    }
  ],
  "pagination": {}
}

Delete Videos

You may delete past broadcasts, highlights, or uploads. The user in the access token must own the videos or be an editor for the channel that owns them.