Basic User Details

Learn to fetch details of users using the Twitch API.

We'll cover the following

Retrieve 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, namely 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.

Request 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.

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
// Importing libraries here
import fetch from "node-fetch";
// Defining the endpoint URL
const endpointUrl = new URL("https://api.twitch.tv/helix/users");
// Defining the header parameters
const headerParameters = {
  Authorization: "Bearer {{USER_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Setting API call options
const options = {
  method: "GET",
  headers: headerParameters,
};
// Function to make API call and fetch our account details
async function fetchUserDetails() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
// Calling the function to fetch account details
fetchUserDetails();

In the code above, we perform the following:

  • Line 2: We import the node-fetch library.

  • Line 5: We define the URL for the users endpoint.

  • Lines 8–11: We define the headers required for the request, including the bearer token and the application's client ID.

  • Lines 14–17: We set the options for the API call, specifying the HTTP request type as GET and providing the request headers.

  • Lines 20–27: We define a function called fetchUserDetails to make a call to the users endpoint.

    • Lines 21–24: We make a call to the endpoint within a try block and print the response from the API.

    • Lines 24–26: We catch any errors or exceptions within a catch block and print them to the console.

  • Line 30: We invoke the fetchUserDetails function. 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 user ID, which 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
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/users");
const headerParameters = {
  Authorization: "Bearer {{APP_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Using the id and login query parameters
const queryParameters = new URLSearchParams({
  id: "{{USER_ID}}",
  login: "twitch",
});
const options = {
  method: "GET",
  headers: headerParameters,
};
async function fetchUserDetails() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
fetchUserDetails();

In the code above, we perform the following:

  • Lines 11–14: We define the query parameters for the call using the id and login parameters.

  • Lines 21–29: We define a function called fetchUserDetails to make a call to the users endpoint.

    • Lines 22–26: Within a try block, we provide the query parameters, make a call to the endpoint, and print the response from the API.

    • Lines 26–28: We catch any errors or exceptions within a catch block and print them to the console.

  • Line 31: We invoke the fetchUserDetails function.

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 fields

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.