Streams Reference
Twitch API v5 is deprecated. Please use the latest version of the 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 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 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. Language is mapped to the broadcast language preference. |
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. Capped at 900. |
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
{
"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 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 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 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. Capped at 900. |
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
{
"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
},
...
]
}