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