Basic User Details

Learn to fetch details of users using the Twitch API.

We'll cover the following

Fetch user details

As users, we're interested in viewing not only our own details but also the details of other streamers. The Twitch API provides an endpoint for this exact purpose, the users endpoint. By sending a GET request to this endpoint, we can retrieve the details of any user we specify as parameters.

Here’s the URL for this endpoint:

https://api.twitch.tv/helix/users

All calls to this endpoint need to be authorized either with an app or a user access token. Additionally, our user access token requires the user:read:email scope if we want to view a user's email address in the response.

We'll try using both types of tokens in this lesson and see how the response from the API varies according to the type of token.

Input parameters

If we use a user access token, no parameters are required. However, if we provide an app access token, we must use at least one of the optional query parameters below:

Parameter

Type

Category

Description

id

String

Optional

This is the ID of the user we want to fetch the details for. We can provide a maximum of 100 user IDs.

login

String

Optional

This is the login name of the user we want to fetch the details for. We can provide a maximum of 100 login names.

Example calls

Let's try making a couple of requests to this endpoint. First, let's authorize ourselves with a user access token. We’ll use neither of the parameters and view the response from the API.

Note: The code below extracts an ID to be used later, so don't forget to save the extracted value. If your token has expired, return to this lesson and follow the steps to generate a new one.

Press + to interact
import requests
import json
headers = {
    'Authorization' : 'Bearer {{USER_ACCESS_TOKEN}}',
    'Client-Id'     : '{{CLIENT_ID}}'
}
response = requests.get('https://api.twitch.tv/helix/users', headers=headers).json()
print(json.dumps(response, indent=4))

In the code above:

  • Lines 1–2: We import the required libraries.
  • Lines 4–7: We define the headers required for the request, including the bearer token and the application's client ID.
  • Line 9: We make a GET request to the users endpoint.
  • Line 11: We print the response object to the console.

This request fetches our own details by checking the user authenticated with the user access token.

Let's also try a request with an app access token instead. Since at least one of the query parameters is required when using an app access token, we'll provide some parameters this time. This includes our own user ID we extracted from the previous response.

Note: If your token has expired, return to this lesson and follow the steps to generate a new one.

Press + to interact
headers = {
    'Authorization' : 'Bearer {{APP_ACCESS_TOKEN}}',
    'Client-Id'     : '{{CLIENT_ID}}'
}
parameters = {
    'id'    : '{{USER_ID}}',
    'login' : 'twitch'
}
response = requests.get('https://api.twitch.tv/helix/users',
                        headers=headers, params=parameters).json()
print(json.dumps(response, indent=4))

Here, the response includes details for each user we specified in the parameters. We can notice the absence of the email property in the response. This is only read if a user access token with the user:read:email scope is provided.

Response structure

A successful response to a call to this endpoint is in the form of a JSON object with a single top-level property, data. This property is an array of objects, with each object representing a single user. The complete details of the user object are discussed in the table below:

Property

Type

Description

id

String

This is the ID of the user.

login

String

This is the user's login name.

display_name

String

This is the user's display name.

type

String

This is the type of user. Its possible values are "staff", "admin", and "global_mod". For users that fall under none of these types, this value is an empty string—"".

broadcaster_type

String

This is the user's broadcaster type. Its possible values are "partner" and "affiliate". For users that fall under none of these types, this value is an empty string—"".

description

String

This is the public description that the user has set on their account.

profile_image_url

String

This is the static URL of the user's profile image.

offline_image_url

String

This is the static URL of the stream placeholder image that is displayed when the user is offline.

view_count

Integer

This is the total number of views that the user's channel has accumulated.

email

String

This is the user's verified email address. It's only included if we use a user access token with the user:read:email scope.

created_at

String

This is the UTC timestamp of when the user was created.