Stream Tags

Learn to fetch and update Twitch stream tags.

We'll cover the following

Twitch uses a vast number of tags to classify its content into different categories. Users can apply tags to their streams and channels. This makes it easier for viewers to search for and filter results based on the type of content they want to see.

There are three types of tags—stream, category, and automatic. Users can only manage the first type of tag. Twitch manages the other two types. Users can only apply a maximum of five stream tags to their channel.

Get all stream tags

The list of stream tags is quite expansive, and new tags are constantly added based on community feedback. Conveniently, the Twitch API has an endpoint we can use to get a list of all tags. We can send a GET request to the tags endpoint and retrieve a complete list of all the valid stream tags.

The URL for the tags endpoint is as follows:

https://api.twitch.tv/helix/tags/streams

All requests to this endpoint must be authenticated with an app access token.

Request parameters

There are no required parameters. However, we can provide several optional query parameters to filter the returned list of tags:

Parameter

Type

Category

Description

after

String

Optional

This is a cursor value for forward pagination. Each response from this endpoint that has multiple pages returns a cursor value. We can provide this cursor value in the after parameter to return the page of results after the page specified by the cursor.

before

String

Optional

This is a cursor value for backward pagination. Each response from this endpoint that has multiple pages returns a cursor value. We can provide this cursor value in the before parameter to return the page of results before the page specified by the cursor.

first

Integer

Optional

This is the number of streams to be returned per page, with a maximum of 100 results per page. Its default value is 100.

tag_id

String

Optional

This is the ID of the tag that we want to retrieve. We can provide a maximum of 100 tag IDs.

The after and tag_id parameters are mutually exclusive. We can only provide one of these in a single request.

Let's make a sample call to the tags endpoint and authorize ourselves with an app access token.

Note: If your access 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/tags/streams");
const headerParameters = {
  Authorization: "Bearer {{APP_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
const options = {
  method: "GET",
  headers: headerParameters,
};
async function fetchStreamTags() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
fetchStreamTags();

In the code above, we perform the following:

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

  • Lines 15–22: We define a function called fetchStreamTags to make a call to the tags endpoint.

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

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

  • Line 24: We invoke the fetchStreamTags function.

Response fields

The response JSON object consists of two properties—data and pagination. The data property is a list of tag objects, and the pagination property contains a cursor value for pagination.

The data array stores the results where each array element represents a tag. The table below gives an overview of the tag object:

Property

Type

Description

tag_id

String

This is the unique ID of the tag.

is_auto

Boolean

This determines whether the tag is an automatic tag or not. As mentioned earlier, automatic tags are managed by Twitch and users cannot directly apply them to their streams or channels.

localization_names

Object

This is a list of names for the tag in different locales and languages. The object contains key-value pairs of the form <locale>:<name>. The locale is represented as <locale>-<country>, for example, en-us.

localization_descriptions

Object

This is a list of descriptions for the tag in different locales and languages. The object contains key-value pairs of the form <locale>:<description>. The locale is represented as <locale>-<country>, for example, en-us.

Get applied stream tags

The previous endpoint is helpful if we want to retrieve every single tag or view the details of certain tags by specifying the tag_id query parameter. What if we want to see what tags have been applied to a particular channel? The Twitch API has us covered for this with the stream tags endpoint.

We can send a GET request to this endpoint and retrieve the tags specified by the user on their channel. The endpoint requires only the user_id or broadcaster_id to return the list of tags.

The URL for this endpoint is as follows:

https://api.twitch.tv/helix/streams/tags

All calls to this endpoint must be authenticated with an app access token.

Request parameters

This endpoint requires a single query parameter. It doesn’t support any optional parameters. The table below shows the summary of this parameter:

Parameter

Type

Category

Description

broadcaster_id

String

Required

This is the ID of the user for which we want to retrieve the list of tags.

Let's make a sample request to this endpoint using our own ID as the broadcaster_id. We can also provide the IDs of different users by changing the value on line 12 to fetch the tags for other channels.

Press + to interact
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/streams/tags");
const headerParameters = {
  Authorization: "Bearer {{APP_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Specifying the broadcaster for which we want to fetch the list of applied tags
const queryParameters = new URLSearchParams({
  broadcaster_id: "{{USER_ID}}",
});
const options = {
  method: "GET",
  headers: headerParameters,
};
async function fetchAppliedTags() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
fetchAppliedTags();

In the code above, we perform the following:

  • Lines 11–13: We define the query parameters for the request using the broadcaster_id parameter.

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

  • Lines 20–28: We define a function called fetchAppliedTags to make a call to the stream tags endpoint.

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

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

  • Line 30: We invoke the fetchAppliedTags function.

Note: If we have not applied any tags to our channel, the response fields will be empty.

The response object from this endpoint is identical to the response from the tags endpoint. The only difference here is the absence of the pagination property. Since a maximum of only five tags can be applied to a channel, the response from this endpoint does not require pagination.

Update stream tags

We've already learned to fetch tags that have already been applied to a channel. However, what if we want to specify new tags or update old tags on our channel? We can send a PUT request to the stream tags endpoint. Since it's a PUT request, it overwrites all existing tags with new ones.

All requests must be authenticated by a user access token that has the channel:manage:broadcast scope.

Request parameters

This endpoint requires a user ID as a required parameter and the tags we want to apply as the body. The table below discusses these parameters:

Parameter

Parameter Type

Type

Category

Description

broadcaster_id

Query

String

Required

This is the ID of the user for which we want to update tags. This ID must be of the same user who is authenticated with the access token.

tag_ids

Body

Array[String]

Optional

This is an array of IDs of the tags that are to be applied to the channel, with a maximum of five tags at a time. If the array is empty, it’ll remove all the tags on the channel.

Let's make a request to this endpoint, applying the "1 Credit Clear" and "Vtuber" tags to our channel. We can add other stream tag IDs to the array starting on line 17. We have to make sure that the number of tags doesn't exceed five.

Press + to interact
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/streams/tags");
const headerParameters = {
  Authorization: "Bearer {{USER_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
  "Content-Type": "application/json",
};
const queryParameters = new URLSearchParams({
  broadcaster_id: "{{USER_ID}}",
});
// Defining the tags to be added to the channel
const bodyParameters = JSON.stringify({
  tag_ids: [
    "621fb5bf-5498-4d8f-b4ac-db4d40d401bf",   // 1 Credit Clear
    "52d7e4cc-633d-46f5-818c-bb59102d9549",   // Vtuber
  ],
});
const options = {
  method: "PUT",
  headers: headerParameters,
  body: bodyParameters,
};
async function updateStreamTags() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
updateStreamTags();

In the code above, we perform the following:

  • Lines 5–9: We define the headers for the request, specifying the content type as application/json.

  • Lines 11–13: We define the query parameters for the call using the broadcaster_id parameter.

  • Lines 16–21: We define the body parameters using the tag_ids parameter.

  • Lines 23–27: We set the options for the API call, specifying the HTTP request type as PUT and providing the request headers and body.

  • Lines 29–37: We define a function called updateStreamTags to make a call to the stream tags endpoint.

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

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

  • Line 39: We invoke the updateStreamTags function.

The response to this request only contains an HTTP status code. If the code is 204, the request is a success. Otherwise, an error code is sent.

Now that we've updated the tags on our channel, let's run the code for the previous endpoint to fetch the tags for our own channel. If all goes well, it'll return the same tags we applied.