Streams 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.

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