Videos Reference

While you can migrate from v3 to v5, know that v5 is deprecated and will be shutdown in the future. We prefer that you migrated directly to the new Twitch API.

Note: Video IDs appear in many requests and responses. In the responses from video endpoints, the IDs have a “v” prefix. That prefix is not used in requests. (The prefix was required in prior versions of the API but is deprecated.)

Endpoint	Description
Get Video	Gets a specified video object.
Get Top Videos	Gets the top videos based on viewcount, optionally filtered by game or time period.
Get Followed Videos	Gets the videos from channels the user is following based on the OAuth token provided.
Create Video	Creates a new video in a specified channel. You must be a partner or affiliate to upload VODs. Note: Users must be Partners or Affiliates to upload VODs. The Get Users API will be used to check whether a user is qualified. Videos with the following formats can be uploaded: MP4, MOV, AVI and FLV file formats; AAC audio; h264 codec; up to 10Mbps bitrate; up to 1080p/60FPS. There is a rate limit of 5 simultaneous uploads per user, with a maximum of 100 uploads in 24 hours. The video title specified in the URL must be no more than 100 characters. The response contains important information for use in future API calls; in particular, the URL where you will upload video parts and the token you will use to upload them. Upload tokens expire after 1 day. If you lose the token or it expires, you must start a new upload and get a new token.
Upload Video Part	Uploads part of a video. Each part of a video is uploaded with a separate request. You must include the length of the content (in bytes) in a required `content-length` header. The body of the request is a `byte[]` that contains the video data. There are two required query-string parameters: The location of the video part in the complete video. The value of this is 1-based. The upload token returned by Create Video. Each video part except the last part must be at least 5 MB and at most 25 MB. The total of all parts cannot exceed 10 GB.
Complete Video Upload	After you upload all the parts of a video, you complete the upload process with this endpoint. The upload token that was returned by Create Video is specified in a required query-string parameter.
Update Video	Updates information about a specified video that was already created.
Delete Video	Deletes a specified video. The video can be any type of VOD (Video on Demand): past broadcasts (videos created from a live Twitch stream), highlights (cut from past broadcasts), or uploads (manually uploaded by broadcasters).

Get Video

✎

Gets a specified video object.

Authentication

None

URL

GET https://api.twitch.tv/kraken/videos/

Optional Query String Parameters

None

Example Request

This returns the object for video 106400740.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/videos/106400740'

Example Response

{
   "_id": "v106400740",
   "broadcast_id": 1,
   "broadcast_type": "upload",
   "channel": {
       "_id": "44322889",
       "name": "dallas",
       "display_name": "dallas"
   },
   "created_at": "2016-12-10T00:46:44Z",
   "description": "Protect your chat with AutoMod! ",
   "description_html": "Protect your chat with AutoMod!
",
   "fps": {
      "1080p": 23.9767661758746,
      "144p": 23.9767661758746,
      "240p": 23.9767661758746,
      "360p": 23.9767661758746,
      "480p": 23.9767661758746,
      "720p": 23.9767661758746
   },
   "game": "",
   "language": "en",
   "length": 29,
   "muted_segments": [
        {
            "duration": 180,
            "offset": 0
        },
        {
            "duration": 360,
            "offset": 2340
        },
        {
            "duration": 360,
            "offset": 5220
        },
        {
            "duration": 360,
            "offset": 7020
        }
    ],
   "preview": {
      "large": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-640x360.jpg",
      "medium": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-320x180.jpg",
      "small": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-80x45.jpg",
      "template": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-{width}x{height}.jpg"
   },
   "published_at": "2016-12-12T18:19:18Z",
   "resolutions": {
      "1080p": "1920x1080",
      "144p": "256x144",
      "240p": "426x240",
      "360p": "640x360",
      "480p": "852x480",
      "720p": "1280x720"
   },
   "status": "recorded",
   "tag_list": "",
   "thumbnails": {
      "large": [{
         "type": "generated",
         "url": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-640x360.jpg"
      }],
      "medium": [{
         "type": "generated",
         "url": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-320x180.jpg"
      }],
      "small": [{
         "type": "generated",
         "url": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-80x45.jpg"
      }],
      "template": [{
         "type": "generated",
         "url": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-{width}x{height}.jpg"
      }]
   },
   "title": "Introducing AutoMod",
   "url": "https://www.twitch.tv/twitch/v/106400740",
   "viewable": "public",
   "viewable_at": null,
   "views": 7638
}

Get Top Videos

✎

Gets the top videos based on viewcount, optionally filtered by game or time period.

Authentication

None

URL

GET https://api.twitch.tv/kraken/videos/top

Optional Query String Parameters

Name	Type	Description
`limit`	integer	Maximum number of objects to return. Default: 10. Maximum: 100.
`offset`	integer	Object offset for pagination of reults. Default: 0. Maximum: 500.
`game`	string	Constrains videos by game. A game name can be retrieved using the Search Games endpoint.
`period`	string	Specifies the window of time to search. Valid values: `week`, `month`, `all`. Default: `week`
`broadcast_type`	comma-separated list	Constrains the type of videos returned. Valid values: (any combination of) `archive`, `highlight`, `upload`, Default: all types (no filter).
`language`	comma-separated list	Constrains the languages of videos returned. Examples: `es`, `en,es,th`. If no language is specified, all languages are returned. Default: `""`.
`sort`	string	Valid values: * `time`: Videos are sorted by publication time, most recent first. * `views`: Videos are sorted by view count, in descending order.

Example Request

This returns the top video objects for the Overwatch game during the past month.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/videos/top?period=month&game=Overwatch'

Example Response

{
    "vods": [{
      "_id": "v101568088",
      "broadcast_id": 23680870240,
      "broadcast_type": "highlight",
      "channel": {
            "_id": "28230875",
            "display_name": "Talespin",
            "name": "talespin"
      },
      "created_at": "2016-11-17T06:24:46Z",
      "description": "gg",
      "description_html": "gg
",
      "fps": {
         "chunked": 59.9726125301009,
         "high": 29.9993664424577,
         "low": 30.0000611327453,
         "medium": 29.9993664424577,
         "mobile": 30.0000611327453
      },
      "game": "Overwatch",
      "language": "en",
      "length": 1272,
      "preview": {
         "large": "https://static-cdn.jtvnw.net/s3_vods/e273175ca1_talespin_23680870240_548725280//thumb/thumb101568088-640x360.jpg",
         "medium": "https://static-cdn.jtvnw.net/s3_vods/e273175ca1_talespin_23680870240_548725280//thumb/thumb101568088-320x180.jpg",
         "small": "https://static-cdn.jtvnw.net/s3_vods/e273175ca1_talespin_23680870240_548725280//thumb/thumb101568088-80x45.jpg",
         "template": "https://static-cdn.jtvnw.net/s3_vods/e273175ca1_talespin_23680870240_548725280//thumb/thumb101568088-{width}x{height}.jpg"
      },
      "published_at": "2016-11-17T06:24:46Z",
      "resolutions": {
         "chunked": "1280x720",
         "high": "1280x720",
         "low": "640x360",
         "medium": "852x480",
         "mobile": "400x226"
      },
      "status": "recorded",
      "tag_list": "overwatch talespin pharah reinhardt ggez",
      "thumbnails": {
         "large": [{
            "type": "generated",
            "url": "https://static-cdn.jtvnw.net/s3_vods/e273175ca1_talespin_23680870240_548725280//thumb/thumb101568088-640x360.jpg"
         }],
         "medium": [{
            "type": "generated",
            "url": "https://static-cdn.jtvnw.net/s3_vods/e273175ca1_talespin_23680870240_548725280//thumb/thumb101568088-320x180.jpg"
         }],
         "small": [{
            "type": "generated",
            "url": "https://static-cdn.jtvnw.net/s3_vods/e273175ca1_talespin_23680870240_548725280//thumb/thumb101568088-80x45.jpg"
         }],
         "template": [{
            "type": "generated",
            "url": "https://static-cdn.jtvnw.net/s3_vods/e273175ca1_talespin_23680870240_548725280//thumb/thumb101568088-{width}x{height}.jpg"
         }]
      },
      "title": "Talespin vs Gods 1v1 (Pharah & Reinhardt)",
      "url": "https://www.twitch.tv/talespin/v/101568088",
      "viewable": "public",
      "viewable_at": null,
      "views": 16426
   },
   ...
   ]
}

Get Followed Videos

✎

Gets the videos from channels followed by a user, based on a specified OAuth token.

Authentication

Required scope: user_read

URL

GET https://api.twitch.tv/kraken/videos/followed

Optional Query String Parameters

Name	Type	Description
`limit`	integer	Maximum number of objects to return, sorted by creation date. Default: 10. Maximum: 100.
`offset`	integer	Object offset for pagination of results. Default: 0.
`broadcast_type`	comma-separated list	Constrains the type of videos returned. Valid values: (any combination of) `archive`, `highlight`, `upload`. Default: all types (no filter).
`language`	comma-separated list	Constrains the languages of videos returned. Examples: `es`, `en,es,th`. If no language is specified, all languages are returned. Default: `""`.
`sort`	string	Valid values: * `time`: Videos are sorted by publication time, most recent first. * `views`: Videos are sorted by view count, in descending order.

Example Request

This returns the 10 most recently created videos in the channels the authorized user is following.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/kraken/videos/followed'

Example Response

{
   "videos": [{
      "_id": "v107666453",
      "broadcast_id": 23939865056,
      "broadcast_type": "archive",
      "channel": {
         "_id": 14836307,
         "display_name": "TrumpSC",
         "name": "trumpsc"
      },
      "created_at": "2016-12-15T20:33:02Z",
      "description": null,
      "description_html": null,
      "fps": {
         "audio_only": 0,
         "chunked": 60,
         "high": 26.25,
         "low": 26.25,
         "medium": 26.25,
         "mobile": 26.25
      },
      "game": "Hearthstone: Heroes of Warcraft",
      "language": "en",
      "length": 6368,
      "preview": {
         "large": "https://static-cdn.jtvnw.net/v1/AUTH_system/vods_631b/trumpsc_23939865056_564912068/thumb/thumb0-640x360.jpg",
         "medium": "https://static-cdn.jtvnw.net/v1/AUTH_system/vods_631b/trumpsc_23939865056_564912068/thumb/thumb0-320x180.jpg",
         "small": "https://static-cdn.jtvnw.net/v1/AUTH_system/vods_631b/trumpsc_23939865056_564912068/thumb/thumb0-80x45.jpg",
         "template": "https://static-cdn.jtvnw.net/v1/AUTH_system/vods_631b/trumpsc_23939865056_564912068/thumb/thumb0-{width}x{height}.jpg"
      },
      "published_at": "2016-12-15T20:33:02Z",
      "resolutions": {
         "chunked": "1920x1080",
         "high": "1280x720",
         "low": "640x360",
         "medium": "852x480",
         "mobile": "400x226"
      },
      "status": "recording",
      "tag_list": "",
      "thumbnails": {
         "large": [{
            "type": "generated",
            "url": "https://static-cdn.jtvnw.net/v1/AUTH_system/vods_631b/trumpsc_23939865056_564912068/thumb/thumb0-640x360.jpg"
         }],
         "medium": [{
            "type": "generated",
            "url": "https://static-cdn.jtvnw.net/v1/AUTH_system/vods_631b/trumpsc_23939865056_564912068/thumb/thumb0-320x180.jpg"
         }],
         "small": [{
            "type": "generated",
            "url": "https://static-cdn.jtvnw.net/v1/AUTH_system/vods_631b/trumpsc_23939865056_564912068/thumb/thumb0-80x45.jpg"
         }],
         "template": [{
            "type": "generated",
            "url": "https://static-cdn.jtvnw.net/v1/AUTH_system/vods_631b/trumpsc_23939865056_564912068/thumb/thumb0-{width}x{height}.jpg"
         }]
      },
      "title": "TSM Trump Renolock",
      "url": "https://www.twitch.tv/trumpsc/v/107666453",
      "viewable": "public",
      "viewable_at": null,
      "views": 10
   },
   ...
   ]
}

Create Video

✎

Creates a new video in a specified channel.

Videos with the following formats can be uploaded:

MP4, MOV, AVI and FLV file formats
AAC audio
h264 codec
Up to 10Mbps bitrate
Up to 1080p/60FPS

There is a rate limit of 5 simultaneous uploads per user, with a maximum of 100 uploads in 24 hours. The video title specified in the URL must be no more than 100 characters.

The response contains important information for use in future calls; in particular, the URL where you will upload video parts and the token you will use to upload them. Upload tokens expire after 1 day. If you lose the token or it expires, you must start a new upload and get a new token.

Also see the Video Upload guide.

Authentication

Required scope: channel_editor

URL

POST https://api.twitch.tv/kraken/videos?channel_id=&title=

Optional Query String Parameters

Name	Type	Description
`description`	string	Short description of the video.
`game`	string	Name of the game in the video.
`language`	string	Language of the video (for example, en).
`tag_list`	string	Comma-separated list of tags describing the video (for example, “airplanes,scary”). Maximum: 100 characters per tag, 500 characters for the entire list.
`viewable`	string	Specifies who can view the video. Valid values: `public` (the video is viewable by everyone) or `private` (the video is viewable only by the owner and channel editors). Default: `public`.
`viewable_at`	RFC3339 date	Date when the video will become public. This takes effect only if `viewable=private`.

Example Request

This creates a video entitled “Test video” in the 44322889 channel.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X POST 'https://api.twitch.tv/kraken/videos?channel_id=44322889&title=Test video'

Example Response

The video ID and upload token returned here are used by Upload Video Part and Complete Video Upload.

{
	"upload": {
		"token": "7_STl2gsKwDy1mHj2k95ld3aodDl3E_NzzQdSlN9ll0p6Ct0xFhvrO5bWu7tGUKEH5jtD_hjB9q3X4vTOQ000B1UcmMxduT30FuHhAmFYgYf7DoJE9PVvGRZqk9WQAR2ZGphUpj_237smnjE2gMoaQ--",
		"url": "https://uploads.twitch.tv/upload/132561385"
	},
	"video": {
		"title": "Test video",
		"description": "",
		"description_html": "",
		"broadcast_id": 1,
		"broadcast_type": "upload",
		"status": "created",
		"tag_list": "",
		"views": 0,
		"url": "https://www.twitch.tv/videos/132561385",
		"language": "en",
		"created_at": "2017-03-31T22:59:00Z",
		"viewable": "public",
		"viewable_at": null,
		"published_at": null,
		"_id": "v106400740",
		"recorded_at": "2017-03-31T22:59:00Z",
		"game": "",
		"length": 0,
		"preview": {
			"small": "https://vod-secure.twitch.tv/_404/404_processing_80x45.png",
			"medium": "https://vod-secure.twitch.tv/_404/404_processing_320x180.png",
			"large": "https://vod-secure.twitch.tv/_404/404_processing_640x360.png",
			"template": "https://vod-secure.twitch.tv/_404/404_processing_{width}x{height}.png"
		},
		"animated_preview_url": "https://vod-storyboards.twitch.tv/dallas/132561385/1d283591-a423-4f57-9656-a332d3949b55/storyboards/132561385-strip-0.jpg",
		"thumbnails": {
			"small": [],
			"medium": [],
			"large": [],
			"template": []
		},
		"fps": {},
		"resolutions": {},
		"channel": {
			"_id": "44322889",
			"name": "dallas",
			"display_name": "dallas"
		}
	}
}

Upload Video Part

✎

Uploads part of a video. Each part of a video is uploaded with a separate request.

You must include the length of the content (in bytes) in a required content-length header. The body of the request is a byte[] that contains the video data.

There are two required query-string parameters:

The location of the video part in the complete video. The value of this is 1-based.
The upload token returned by Create Video.

Each video part except the last part must be at least 5 MB and at most 25 MB. The total of all parts cannot exceed 10 GB.

Authentication

For upload endpoints, authentication is done via the upload_token specified in the URL.

URL

PUT https://uploads.twitch.tv/upload/

Note: Upload endpoints use a different site (uploads.twitch.tv) than the other video endpoints.

Optional Query String Parameters

None

Example Request

This uploads the first part (test.mp4) of video 106400740. For upload endpoints, client ID need not be specified.

curl -H 'Content-Length: 8896493' \
--data-binary "@test.mp4" \
-X PUT 'https://uploads.twitch.tv/upload/106400740?part=1&upload_token=7_STl2gsKwDy1mHj2k95ld3aodDl3E_NzzQdSlN9ll0p6Ct0xFhvrO5bWu7tGUKEH5jtD_hjB9q3X4vTOQ000B1UcmMxduT30FuHhAmFYgYf7DoJE9PVvGRZqk9WQAR2ZGphUpj_237smnjE2gMoaQ--'

Example Response

200 OK

Complete Video Upload

✎

After you upload all the parts of a video, you complete the upload process with this endpoint.

The upload token that was returned by Create Video is specified in a required query-string parameter.

Authentication

For upload endpoints, authentication is done via the upload_token specified in the URL.

URL

POST https://uploads.twitch.tv/upload/

Note: Upload endpoints use a different site (uploads.twitch.tv) than the other video endpoints.

Optional Query String Parameters

None

Example Request

This completes the upload of video 106400740. For upload endpoints, client ID need not be specified.

curl -X POST 'https://uploads.twitch.tv/upload/106400740/complete?upload_token=7_STl2gsKwDy1mHj2k95ld3aodDl3E_NzzQdSlN9ll0p6Ct0xFhvrO5bWu7tGUKEH5jtD_hjB9q3X4vTOQ000B1UcmMxduT30FuHhAmFYgYf7DoJE9PVvGRZqk9WQAR2ZGphUpj_237smnjE2gMoaQ--'

Example Response

200 OK

Update Video

✎

Updates information about a specified video that was already created.

Authentication

Required scope: channel_editor

URL

PUT https://api.twitch.tv/kraken/videos/

Optional Query String Parameters

Name	Type	Description
`description`	string	Short description of the video.
`game`	string	Name of the game in the video.
`language`	string	Language of the video (for example, en).
`tag_list`	string	Comma-separated list of tags describing the video (for example, “airplanes,scary”). Maximum: 100 characters per tag, 500 characters for the entire list.
`title`	string	Title of the video. Maximum 100 characters.

Example Request

This updates the title of video 106400740.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X PUT 'https://api.twitch.tv/kraken/videos/106400740?title=Updated test video'

Example Response

{
    "title": "Updated test video",
    "description": "Protect your chat with AutoMod! ",
    "description_html": "Protect your chat with AutoMod!
",
    "broadcast_id": 1,
    "broadcast_type": "upload",
    "status": "recorded",
    "tag_list": "",
    "views": 11606,
    "url": "https://www.twitch.tv/videos/106400740",
    "language": "en",
    "created_at": "2016-12-10T00:46:44Z",
    "viewable": "public",
    "viewable_at": null,
    "published_at": "2016-12-12T18:19:18Z",
    "_id": "v106400740",
    "recorded_at": "2016-12-10T00:46:44Z",
    "game": "",
    "length": 29,
    "preview": {
        "small": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-80x45.jpg",
        "medium": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-320x180.jpg",
        "large": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-640x360.jpg",
        "template": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-{width}x{height}.jpg"
    },
    "animated_preview_url": "https://vod-storyboards.twitch.tv/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/storyboards/106400740-strip-0.jpg",
    "thumbnails": {
        "small": [
            {
                "type": "generated",
                "url": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-80x45.jpg"
            }
        ],
        "medium": [
            {
                "type": "generated",
                "url": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-320x180.jpg"
            }
        ],
        "large": [
            {
                "type": "generated",
                "url": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-640x360.jpg"
            }
        ],
        "template": [
            {
                "type": "generated",
                "url": "https://static-cdn.jtvnw.net/s3_vods/twitch/106400740/f2979575-fa80-4ad9-9665-a074d510a03a/thumb/index-0000000000-{width}x{height}.jpg"
            }
        ]
    },
    "fps": {
        "1080p": 23.976766175874648,
        "144p": 23.976766175874648,
        "240p": 23.976766175874648,
        "360p": 23.976766175874648,
        "480p": 23.976766175874648,
        "720p": 23.976766175874648
    },
    "resolutions": {
        "1080p": "1920x1080",
        "144p": "256x144",
        "240p": "426x240",
        "360p": "640x360",
        "480p": "852x480",
        "720p": "1280x720"
    },
    "channel": {
        "_id": "44322889",
        "name": "dallas",
        "display_name": "dallas"
    }
}

Delete Video

✎

Deletes a specified video.

The video can be any type of VOD (Video on Demand): past broadcasts (videos created from a live Twitch stream), highlights (cut from past broadcasts), or uploads (manually uploaded by broadcasters).

Authentication

Required scope: channel_editor

URL

DELETE https://api.twitch.tv/kraken/videos/

Optional Query String Parameters

None

Example Request

This deletes video 106400740.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X DELETE 'https://api.twitch.tv/kraken/videos/106400740'

Example Response

200 OK
{"ok":"true"}