Users Reference
Twitch API v5 is deprecated. Please use the latest version of the Twitch API.
Endpoint | Description |
---|---|
Get User | Gets a user object based on the OAuth token provided. Get User returns more data than Get User by ID, because Get User is privileged. |
Get User by ID | Gets a specified user object. |
Get Users | Gets the user objects for the specified Twitch login names (up to 100). If a specified user’s Twitch-registered email address is not verified, null is returned for that user. |
Get User Emotes | Gets a list of the emojis and emoticons that the specified user can use in chat. These are both the globally available ones and the channel-specific ones (which can be accessed by any user subscribed to the channel). |
Check User Subscription by Channel | Checks if a specified user is subscribed to a specified channel. |
Get User Follows | Gets a list of all channels followed by a specified user, sorted by the date when they started following each channel. |
Check User Follows by Channel | Checks if a specified user follows a specified channel. If the user is following the channel, a follow object is returned. |
Follow Channel | Adds a specified user to the followers of a specified channel. There is an error response ( |
Unfollow Channel | Deletes a specified user from the followers of a specified channel. |
Get User Block List | Gets a specified user’s block list. |
Block User | Blocks a user; that is, adds a specified target user to the blocks list of a specified source user. |
Unblock User | Unblocks a user; that is, deletes a specified target user from the blocks list of a specified source user. There is an error if the target user is not on the source user’s block list ( |
Get User
✎Gets a user object based on the OAuth token provided.
Get User returns more data than Get User by ID, because Get User is privileged.
Authentication
Required scope: user_read
URL
GET https://api.twitch.tv/kraken/user
Note: This URL uses “user” (singular), not “users” like the other endpoints in this category.
Optional Query Parameters
None
Example Request
This returns the user object 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/user'
Example Response
{
"_id": 44322889,
"bio": "Just a gamer playing games and chatting. :)",
"created_at": "2013-06-03T19:12:02Z",
"display_name": "dallas",
"email": "email-address@provider.com",
"email_verified": true,
"logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-profile_image-1a2c906ee2c35f12-300x300.png",
"name": "dallas",
"notifications": {
"email": false,
"push": true
},
"partnered": false,
"twitter_connected": false,
"type": "staff",
"updated_at": "2016-12-14T01:01:44Z"
}
Get User by ID
✎Gets a specified user object.
Authentication
None
URL
GET https://api.twitch.tv/kraken/users/<user ID>
Optional Query Parameters
None
Example Request
This returns the object for user 44322889.
curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/users/44322889'
Example Response
{
"_id": "44322889",
"bio": "Just a gamer playing games and chatting. :)",
"created_at": "2013-06-03T19:12:02.580593Z",
"display_name": "dallas",
"logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-profile_image-1a2c906ee2c35f12-300x300.png",
"name": "dallas",
"type": "staff",
"updated_at": "2016-12-13T16:31:55.958584Z"
}
Get Users
✎Gets the user objects for the specified Twitch login names (up to 100).
If a specified user’s Twitch-registered email address is not verified, null is returned for that user.
Authentication
Required scope: user_read
URL
GET https://api.twitch.tv/kraken/users?login=<user IDs>
Optional Query Parameters
None
Example Request
This returns the user objects for two users, dallas and dallasnchains.
curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET https://api.twitch.tv/kraken/users?login=dallas,dallasnchains
Example Response
{
"_total": 2,
"users": [
{
"_id": "44322889",
"bio": "Just a gamer playing games and chatting. :)",
"created_at": "2013-06-03T19:12:02.580593Z",
"display_name": "dallas",
"logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-profile_image-1a2c906ee2c35f12-300x300.png",
"name": "dallas",
"type": "staff",
"updated_at": "2017-02-09T16:32:06.784398Z"
},
{
"_id": "129454141",
"bio": null,
"created_at": "2016-07-13T14:40:42.398257Z",
"display_name": "dallasnchains",
"logo": null,
"name": "dallasnchains",
"type": "user",
"updated_at": "2017-02-04T14:32:38.626459Z"
}
]
}
Get User Emotes
✎Gets a list of the emojis and emoticons that the specified user can use in chat. These are both the globally available ones and the channel-specific ones (which can be accessed by any user subscribed to the channel).
Authentication
Required scope: user_subscriptions
URL
GET https://api.twitch.tv/kraken/users/<user ID>/emotes
Optional Query Parameters
None
Example Request
This gets a list of the emotes that user 44322889 can use in chat.
curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/kraken/users/44322889/emotes'
Example Response
{
"emoticon_sets": {
"0": [
{
"code": "Kappa",
"id": 25
},
{
"code": "FrankerZ",
"id": 65
},
{
"code": "PogChamp",
"id": 88
},
...
],
"17937": [
{
"code": "moon2HAHAA",
"id": 110379
},
{
"code": "moon2AWW",
"id": 110380
},
{
"code": "moon2DUMB",
"id": 115545
},
...
],
"19194": [
{
"code": "FlipThis",
"id": 115844
},
{
"code": "TableHere",
"id": 115845
},
{
"code": "ScaredyCat",
"id": 115846
},
{
"code": "KappaHD",
"id": 115847
},
{
"code": "MiniK",
"id": 115848
}
]
}
}
Check User Subscription by Channel
✎Checks if a specified user is subscribed to a specified channel.
There is an error response (422 Unprocessable Entity
) if the channel does not have a subscription program.
Authentication
Required scope: user_subscriptions
URL
GET https://api.twitch.tv/kraken/users/<user ID>/subscriptions/<channel ID>
Optional Query Parameters
None
Example Request
This checks whether user 44322889 is subscribed to channel 19571752.
curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/kraken/users/44322889/subscriptions/19571752'
Example Response if the User is Subscribed to the Channel
{
"_id": "ac2f1248993eaf97e71721458bd88aae66c92330",
"sub_plan": "3000",
"sub_plan_name": "Channel Subscription (forstycup) - $24.99 Sub",
"channel": {
"_id": "19571752",
"broadcaster_language": "en",
"created_at": "2011-01-16T04:35:51Z",
"display_name": "forstycup",
"followers": 397,
"game": "Final Fantasy XV",
"language": "en",
"logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/forstycup-profile_image-940fb4ca1e5949c0-300x300.png",
"mature": true,
"name": "forstycup",
"partner": true,
"profile_banner": null,
"profile_banner_background_color": null,
"status": "[Blind] Moar Sidequests! Let's explore.",
"updated_at": "2017-04-06T09:00:41Z",
"url": "http://localhost:3000/forstycup",
"video_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/forstycup-channel_offline_image-f7274322063da225-1920x1080.png",
"views": 5705
},
"created_at": "2017-04-08T19:54:24Z"
}
Example Response if the User is Not Subscribed to the Channel
{
"error": "Not Found",
"message": "dallas has no subscriptions to twitch",
"status": 404
}
Get User Follows
✎Gets a list of all channels followed by a specified user, sorted by the date when they started following each channel.
Authentication
None
URL
GET https://api.twitch.tv/kraken/users/<user ID>/follows/channels
Optional Query Parameters
Name | Type | Description |
---|---|---|
limit |
integer | Maximum number of most-recent objects to return. Default: 25. Maximum: 100. |
offset |
integer | Object offset for pagination of results. Default: 0. |
direction |
string | Sorting direction. Valid values: asc , desc . Default: desc (newest first). |
sortby |
string | Sorting key. Valid values: created_at , last_broadcast , login . Default: created_at . |
Example Request
This gets a list of up to 25 channels followed by user 44322889 most recently.
curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/users/44322889/follows/channels'
Example Response
{
"_total": 27,
"follows": [
{
"created_at": "2016-09-16T20:37:39Z",
"notifications": false,
"channel": {
"_id": 12826,
"background": null,
"banner": null,
"broadcaster_language": "en",
"created_at": "2007-05-22T10:39:54Z",
"delay": null,
"display_name": "Twitch",
"followers": 530641,
"game": "Gaming Talk Shows",
"language": "en",
"logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_image-bd6df6672afc7497-300x300.png",
"mature": false,
"name": "twitch",
"partner": true,
"profile_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_banner-6936c61353e4aeed-480.png",
"profile_banner_background_color": null,
"status": "Twitch Weekly",
"updated_at": "2016-12-13T18:35:28Z",
"url": "https://www.twitch.tv/twitch",
"video_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-channel_offline_image-d687d9e22677a1b6-640x360.png",
"views": 109064987
}
},
...
]
}
Check User Follows by Channel
✎Checks if a specified user follows a specified channel. If the user is following the channel, a follow object is returned.
Authentication
None
URL
GET https://api.twitch.tv/kraken/users/<user ID>/follows/channels/<channel ID>
Optional Query Parameters
None
Example Request
This checks if user 44322889 follows channel 129454141.
curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/users/44322889/follows/channels/129454141'
Example Response if the User is Following the Channel
{
"created_at": "2016-04-06T15:17:42.97074Z",
"notifications": false,
"channel": {
"_id": 26610234,
"broadcaster_language": "en",
"created_at": "2011-12-06T18:20:34.075423Z",
"display_name": "CohhCarnage",
"followers": 695284,
"game": "Job Simulator: The 2050 Archives",
"language": "en",
"logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/cohhcarnage-profile_image-170de4e7853fde48-300x300.png",
"mature": false,
"name": "cohhcarnage",
"partner": true,
"profile_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/cohhcarnage-profile_banner-79b9a8fd82a49ee8-480.png",
"profile_banner_background_color": "",
"status": "[ !Shirt ] Weds: No Afternoon Stream, Thurs: DF at 2pm EST, Fri: Normal Schedule :) - !Prime - !Achievements - !4Year",
"updated_at": "2016-12-14T17:35:10.257098Z",
"url": "https://www.twitch.tv/cohhcarnage",
"video_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/cohhcarnage-channel_offline_image-c50f829c25e3e825-1920x1080.png",
"views": 47343660
}
}
Example Response if the User is Not Following the Channel
{
"error": "Not Found",
"message": "44322889 is not following 129454141",
"status": 404
}
Follow Channel
✎Adds a specified user to the followers of a specified channel.
There is an error response (422 Unprocessable Entity
) if the channel could not be followed.
Authentication
Required scope: user_follows_edit
URL
PUT https://api.twitch.tv/kraken/users/<user ID>/follows/channels/<channel ID>
Optional Parameter in the Request Body
Name | Type | Description |
---|---|---|
notifications |
boolean | If true , the user gets email or push notifications (depending on the user’s notification settings) when the channel goes live. Default: false . |
Example Request
This updates user 44322889 to follow channel 129454141.
curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X PUT 'https://api.twitch.tv/kraken/users/44322889/follows/channels/129454141'
Example Response if the Update Succeeds
{
"channel": {
"_id": 129454141,
"broadcaster_language": null,
"created_at": "2016-07-13T14:40:42Z",
"display_name": "dallasnchains",
"followers": 2,
"game": null,
"language": "en",
"logo": null,
"mature": null,
"name": "dallasnchains",
"partner": false,
"profile_banner": null,
"profile_banner_background_color": null,
"status": null,
"updated_at": "2016-12-14T00:32:17Z",
"url": "https://www.twitch.tv/dallasnchains",
"video_banner": null,
"views": 6
},
"created_at": "2016-12-14T10:28:32-08:00",
"notifications": false
}
Unfollow Channel
✎Deletes a specified user from the followers of a specified channel.
Authentication
Required scope: user_follows_edit
URL
DELETE https://api.twitch.tv/kraken/users/<user ID>/follows/channels/<channel ID>
Optional Query Parameters
None
Example Request
This updates user 44322889 to stop following channel 129454141.
curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X DELETE 'https://api.twitch.tv/kraken/users/44322889/follows/channels/129454141'
Example Response
204 No Content
Get User Block List
✎Gets a specified user’s block list. List sorted by recency, newest first.
Authentication
Required scope: user_blocks_read
URL
GET https://api.twitch.tv/kraken/users/<user ID>/blocks
Optional Query Parameters
Name | Type | Description |
---|---|---|
limit |
integer | Maximum number of objects in array. Default: 25. Maximum: 100. |
offset |
integer | Object offset for pagination. Default: 0. |
Example Request
This gets the block list for user 44322889.
curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/kraken/users/44322889/blocks'
Example Response
{
"_total": 4,
"blocks":
[{
"user": {
"_id": 129454141,
"bio": null,
"created_at": "2016-07-13T14:40:42Z",
"display_name": "dallasnchains",
"logo": null,
"name": "dallasnchains",
"type": "user",
"updated_at": "2016-12-14T00:32:17Z"
}
},
...
]
}
Block User
✎Blocks a user; that is, adds a specified target user to the blocks list of a specified source user.
Authentication
Required scope: user_blocks_edit
URL
PUT https://api.twitch.tv/kraken/users/<source user ID>/blocks/<target user ID>
Optional Query Parameters
None
Example Request
This adds user 129454141 to the blocks list of user 44322889.
curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X PUT 'https://api.twitch.tv/kraken/users/44322889/blocks/129454141'
Example Response
{
"_id": 34105628,
"updated_at": "2016-12-15T18:57:08Z",
"user": {
"_id": 129454141,
"bio": null,
"created_at": "2016-07-13T14:40:42Z",
"display_name": "dallasnchains",
"logo": null,
"name": "dallasnchains",
"type": "user",
"updated_at": "2016-12-14T00:32:17Z"
}
}
Unblock User
✎Unblocks a user; that is, deletes a specified target user from the blocks list of a specified source user.
There is an error if the target user is not on the source user’s block list (404 Not Found
) or the delete failed (422 Unprocessable Entity
).
Authentication
Required scope: user_blocks_edit
URL
DELETE https://api.twitch.tv/kraken/users/<source user ID>/blocks/<target user ID>
Optional Query Parameters
None
Example Request
This deletes user 129454141 from the blocks list of user 44322889.
curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X DELETE 'https://api.twitch.tv/kraken/users/44322889/blocks/129454141'
Example Response on Success
204 No Content