Streams

Endpoint Description
Get Stream by User Gets stream information (the stream object) for a specified user.
Get Live Streams Gets a list of live streams.
Get Streams Summary Gets a summary of live streams.
Get Featured Streams Gets a list of all featured live streams.
Get Followed Streams Gets a list of online streams a user is following, based on a specified OAuth token.

Get Stream by User

Gets stream information (the stream object) for a specified user.

Authentication

None

URL

GET https://api.twitch.tv/kraken/streams/<channel ID>

Optional Query String Parameter

Name Type Description
stream_type string Constrains the type of streams returned. Valid values: live, playlist, all. Playlists are offline streams of VODs (Video on Demand) that appear live. Default: live.

Example Request

This gets stream information for channel 44322889.

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

Example Response if the Channel is Offline

1
2
3
{
   "stream":null
}

Example Response if the Channel is Live Broadcasting

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
{
   "stream": {
      "_id": 23932774784,
      "game": "BATMAN - The Telltale Series",
      "viewers": 7254,
      "video_height": 720,
      "average_fps": 60,
      "delay": 0,
      "created_at": "2016-12-14T22:49:56Z",
      "is_playlist": false,
      "preview": {
         "small": "https://static-cdn.jtvnw.net/previews-ttv/live_user_dansgaming-80x45.jpg",
         "medium": "https://static-cdn.jtvnw.net/previews-ttv/live_user_dansgaming-320x180.jpg",
         "large": "https://static-cdn.jtvnw.net/previews-ttv/live_user_dansgaming-640x360.jpg",
         "template": "https://static-cdn.jtvnw.net/previews-ttv/live_user_dansgaming-{width}x{height}.jpg"
      },
      "channel": {
         "mature": false,
         "status": "Dan is Batman? - Telltale's Batman",
         "broadcaster_language": "en",
         "display_name": "DansGaming",
         "game": "BATMAN - The Telltale Series",
         "language": "en",
         "_id": 7236692,
         "name": "dansgaming",
         "created_at": "2009-07-15T03:02:41Z",
         "updated_at": "2016-12-15T01:33:58Z",
         "partner": true,
         "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/dansgaming-profile_image-76e4a4ab9388bc9c-300x300.png",
         "video_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/dansgaming-channel_offline_image-d3551503c24c08ad-1920x1080.png",
         "profile_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/dansgaming-profile_banner-4c2b8ece8cd010b4-480.jpeg",
         "profile_banner_background_color": null,
         "url": "https://www.twitch.tv/dansgaming",
         "views": 63906830,
         "followers": 538598
      }
   }
}

Get Live Streams

Gets a list of live streams.

Authentication

None

URL

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

Optional Query String Parameters

Name Type Description
channel comma-separated list of channel IDs Constrains the channel(s) of the streams returned.
game string Constrains the game of the streams returned.
language string Constrains the language of the streams returned. Valid value: a locale ID string; for example, en, fi, es-mx. Only one language can be specified. Default: all languages.
stream_type string Constrains the type of streams returned. Valid values: live, playlist, all. Playlists are offline streams of VODs (Video on Demand) that appear live. Default: live.
limit integer Maximum number of objects to return, sorted by number of viewers. Default: 25. Maximum: 100.
offset integer Object offset for pagination of results. Default: 0.

Example Request

This gets a list of the 25 live streams of Overwatch with the most current viewers.

1
2
3
curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/streams/?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
{
   "_total": 1295,
   "streams": [
   {
      "_id": 23937446096,
      "average_fps": 60,
      "channel": {
            "_id": 121059319,
            "broadcaster_language": "en",
            "created_at": "2016-04-06T04:12:40Z",
            "display_name": "MOONMOON_OW",
            "followers": 251220,
            "game": "Overwatch",
            "language": "en",
            "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/moonmoon_ow-profile_image-0fe586039bb28259-300x300.png",
            "mature": true,
            "name": "moonmoon_ow",
            "partner": true,
            "profile_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/moonmoon_ow-profile_banner-13fbfa1ba07bcd8a-480.png",
            "profile_banner_background_color": null,
            "status": "KKona where my Darryl subs at KKona",
            "updated_at": "2016-12-15T20:04:53Z",
            "url": "https://www.twitch.tv/moonmoon_ow",
            "video_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/moonmoon_ow-channel_offline_image-2b3302e20384eee8-1920x1080.png",
            "views": 9869754
      },
      "created_at": "2016-12-15T14:55:49Z",
      "delay": 0,
      "game": "Overwatch",
      "is_playlist": false,
      "preview": {
            "large": "https://static-cdn.jtvnw.net/previews-ttv/live_user_moonmoon_ow-640x360.jpg",
            "medium": "https://static-cdn.jtvnw.net/previews-ttv/live_user_moonmoon_ow-320x180.jpg",
            "small": "https://static-cdn.jtvnw.net/previews-ttv/live_user_moonmoon_ow-80x45.jpg",
            "template": "https://static-cdn.jtvnw.net/previews-ttv/live_user_moonmoon_ow-{width}x{height}.jpg"
      },
      "video_height": 720,
      "viewers": 11523
   },
      ...
   ]
}

Get Streams Summary

Gets a summary of live streams.

Authentication

None

URL

GET https://api.twitch.tv/kraken/streams/summary

Optional Query String Parameter

Name Type Description
game string Constrains the game of the streams returned.

Example Request

This gets a summary of live streams for Overwatch.

1
2
3
curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/streams/summary?game=Overwatch'

Example Response

1
2
3
4
{
    "channels": 1417,
    "viewers": 19973
}

Gets a list of all featured live streams.

Authentication

None

URL

GET https://api.twitch.tv/kraken/streams/featured

Optional Query String Parameters

Name Type Description
limit integer Maximum number of objects to return, sorted by priority. Default: 25. Maximum: 100.
offset integer Object offset for pagination of results. Default: 0.

Example Request

This gets the 25 top-priority featured live streams.

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

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
{
   "featured": [
   {
      "image": "https://s.jtvnw.net/jtv_user_pictures/hosted_images/bethesda_fp_novTESL",
      "priority": 3,
      "scheduled": true,
      "sponsored": false,
      "stream": {
            "_id": 23939485488,
            "average_fps": 30.9441111462,
            "channel": {
               "_id": 614394,
               "broadcaster_language": "en",
               "created_at": "2008-05-22T14:22:36Z",
               "display_name": "Bethesda",
               "followers": 172116,
               "game": "The Elder Scrolls: Legends",
               "language": "en",
               "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/bethesda-profile_image-1d57ec1547f63ac8-300x300.jpeg",
               "mature": true,
               "name": "bethesda",
               "partner": true,
               "profile_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/bethesda-profile_banner-fcc5a8df410baa06-480.jpeg",
               "profile_banner_background_color": null,
               "status": "The Elder Scrolls: Legends - Chaos Arena with Pete Hines - Thursday, December 15 at 3:00 PM EST",
               "updated_at": "2016-12-15T20:05:12Z",
               "url": "https://www.twitch.tv/bethesda",
               "video_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/bethesda-channel_offline_image-d78d871c05aeadd7-1920x1080.jpeg",
               "views": 9094715
            },
            "created_at": "2016-12-15T19:54:31Z",
            "delay": 0,
            "game": "The Elder Scrolls: Legends",
            "is_playlist": false,
            "preview": {
               "large": "https://static-cdn.jtvnw.net/previews-ttv/live_user_bethesda-640x360.jpg",
               "medium": "https://static-cdn.jtvnw.net/previews-ttv/live_user_bethesda-320x180.jpg",
               "small": "https://static-cdn.jtvnw.net/previews-ttv/live_user_bethesda-80x45.jpg",
               "template": "https://static-cdn.jtvnw.net/previews-ttv/live_user_bethesda-{width}x{height}.jpg"
            },
            "video_height": 1080,
            "viewers": 1724
      },
      "text": "<p>Bethesda\u2019s Pete Hines is back for more Arena and Deckbuilding in The Elder Scrolls: Legends. Download and play for free today!</p>\n\n<br>\n\n\n<p><a href=\"/bethesda\">Click here</a> to watch and chat!</p>\n\n<p><a href=\"pubdev,devrecurring\"></a></p>\n",
      "title": "Bethesda Plays The Elder Scrolls: Legends | More Arena & Deckbuilding"
   }]
}

Get Followed Streams

Gets a list of online streams a user is following, based on a specified OAuth token.

Authentication

Required scope: user_read

URL

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

Optional Query String Parameters

Name Type Description
stream_type string Constrains the type of streams returned. Valid values: live, playlist, all. Playlists are offline streams of VODs (Video on Demand) that appear live. Default: live.
limit integer Maximum number of objects to return. Default: 25. Maximum: 100.
offset integer Object offset for pagination of results. Default: 0.

Example Request

Gets a list of online streams associated with OAuth token cfabdegwdoklmawdzdo98xt2fo512y.

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/streams/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
{
   "_total": 5,
   "streams": [
      {
         "_id": 23937446096,
         "average_fps": 60,
         "channel": {
               "_id": 121059319,
               "broadcaster_language": "en",
               "created_at": "2016-04-06T04:12:40Z",
               "display_name": "MOONMOON_OW",
               "followers": 251103,
               "game": "Overwatch",
               "language": "en",
               "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/moonmoon_ow-profile_image-0fe586039bb28259-300x300.png",
               "mature": true,
               "name": "moonmoon_ow",
               "partner": true,
               "profile_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/moonmoon_ow-profile_banner-13fbfa1ba07bcd8a-480.png",
               "profile_banner_background_color": null,
               "status": "KKona where my Darryl subs at KKona",
               "updated_at": "2016-12-15T19:34:46Z",
               "url": "https://www.twitch.tv/moonmoon_ow",
               "video_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/moonmoon_ow-channel_offline_image-2b3302e20384eee8-1920x1080.png",
               "views": 9865358
         },
         "created_at": "2016-12-15T14:55:49Z",
         "delay": 0,
         "game": "Overwatch",
         "is_playlist": false,
         "preview": {
               "large": "https://static-cdn.jtvnw.net/previews-ttv/live_user_moonmoon_ow-640x360.jpg",
               "medium": "https://static-cdn.jtvnw.net/previews-ttv/live_user_moonmoon_ow-320x180.jpg",
               "small": "https://static-cdn.jtvnw.net/previews-ttv/live_user_moonmoon_ow-80x45.jpg",
               "template": "https://static-cdn.jtvnw.net/previews-ttv/live_user_moonmoon_ow-{width}x{height}.jpg"
         },
         "video_height": 720,
         "viewers": 11211
      },
      ...
   ]
}