Videos

Endpoint Description
Get Video Gets a specified video object.

Note that in prior versions of the API, the specified video ID required a ā€œvā€ prefix. That prefix is deprecated.
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.

Get Video

Gets a specified video object.

Note that in prior versions of the API, the specified video ID required a ā€œvā€ prefix. That prefix is deprecated.

Authentication

None

URL

GET https://api.twitch.tv/kraken/videos/<video ID>

Optional Query String Parameters

None

Example Request

This returns the object for video 106400740.

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

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
{
   "_id": "v106400740",
   "broadcast_id": 1,
   "broadcast_type": "upload",
   "channel": {
      "_id": 12826,
      "display_name": "Twitch",
      "name": "twitch"
   },
   "created_at": "2016-12-10T00:46:44Z",
   "description": "Protect your chat with AutoMod! ",
   "description_html": "Protect your chat with AutoMod!<br>",
   "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.
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: highlight.

Example Request

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

1
2
3
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
    "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<br>",
      "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: highlight.

Example Request

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

1
2
3
4
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
{
   "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
   },
   ...
   ]
}