Streams Reference

Twitch API v5 is deprecated and will be removed on 12/31/18. The new Twitch API is live and we are actively adding new functionality to it.

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.

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

{
   "stream":null
}

Example Response if the Channel is Live Broadcasting

{
   "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.

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

Example Response

{
   "_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.

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

{
    "channels": 1417,
    "viewers": 19973
}

Get Featured Streams

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.

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

{
   "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.

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

{
   "_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
      },
      ...
   ]
}