Users 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 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. Intended for viewers. There is an error response (`422 Unprocessable Entity`) if the channel does not have a subscription program.
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 (`422 Unprocessable Entity`) if the channel could not be followed.
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 (`404 Not Found`) or the delete failed (`422 Unprocessable Entity`).
Create User Connection to Viewer Heartbeat Service (VHS)	Creates a connection between a user (an authenticated Twitch user, linked to a game user) and VHS, and starts returning the user’s VHS data in each heartbeat. The game user is specified by a required `identifier` parameter.
Check User Connection to Viewer Heartbeat Service (VHS)	Checks whether an authenticated Twitch user is connected to VHS. If a connection to the service exists for the specified user, the linked game user’s ID is returned; otherwise, an HTTP 404 response is returned.
Delete User Connection to Viewer Heartbeat Service (VHS)	Deletes the connection between an authenticated Twitch user and VHS.

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 String 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 protected]",
    "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 String 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 String 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 String 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 String 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 String 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 String 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 his 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 String 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 String 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": 
   [{
      "_id": 34105660,
      "updated_at": "2016-12-15T18:58:11Z",
      "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 String 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 String 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

Create User Connection to Viewer Heartbeat Service (VHS)

Creates a connection between a user (an authenticated Twitch user, linked to a game user) and VHS, and starts returning the user’s VHS data in each heartbeat. The game user is specified by a required identifier parameter.

An HTTP 422 response is returned if the game (identified by a client ID) is not configured.

Authentication

Required scope: viewing_activity_read

URL

PUT https://api.twitch.tv/kraken/user/vhs

Note: The VHS URLs employ user (singular), not users.

Optional Query String Parameters

None

Example Request

This creates a connection between the Twitch user identified by OAuth token cfabdegwdoklmawdzdo98xt2fo512, your game user ABC12345 (to whom the Twitch user must be linked), and VHS. It also starts returning the user’s VHS data.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{"identifier": "ABC12345"}' \
-X PUT 'https://api.twitch.tv/kraken/user/vhs'

Example Response on Success

204 No Content

Check User Connection to Viewer Heartbeat Service (VHS)

Checks whether an authenticated Twitch user is connected to VHS.

If a connection to the service exists for the specified user, the linked game user’s ID is returned; otherwise, an HTTP 404 response is returned.

Authentication

Required scope: user_read

URL

GET https://api.twitch.tv/kraken/user/vhs

Note: The VHS URLs employ user (singular), not users.

Optional Query String Parameters

None

Example Request

This checks whether the user identified by OAuth token cfabdegwdoklmawdzdo98xt2fo512y is connected to VHS.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/user/vhs'

Example Response

{
    "identifier": "HRX12345"
}

Delete User Connection to Viewer Heartbeat Service (VHS)

Deletes the connection between an authenticated Twitch user and VHS.

Authentication

Required scope: viewing_activity_read

URL

DELETE https://api.twitch.tv/kraken/user/vhs

Note: The VHS URLs employ user (singular), not users.

Optional Query String Parameters

None

Example Request

This deletes the connection between the user identified by OAuth token cfabdegwdoklmawdzdo98xt2fo512y and VHS.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X DELETE 'https://api.twitch.tv/kraken/user/vhs'

Example Response on Success

204 No Content