Contents

Users Reference

Legacy Twitch API v5 is deprecated and scheduled to be decommissioned on February 28, 2022. For more information, refer to the timeline announcement and the v5 migration guide to 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.
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).

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
}

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
+
Docs Status Support Showcase Blog