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.

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

Example call

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
headers = {
    'Authorization' : 'Bearer {{APP_ACCESS_TOKEN}}',
    'Client-Id'     : '{{CLIENT_ID}}'
}
response = requests.get('https://api.twitch.tv/helix/tags/streams', headers=headers).json()
print(json.dumps(response, indent=4))

Response structure

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.

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

Example call

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 7 to fetch the tags for other channels.

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

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 the existing tags with the new tags.

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

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

Example call

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 12. We just have to make sure that the length doesn't exceed five.

Press + to interact
headers = {
    'Authorization' : 'Bearer {{USER_ACCESS_TOKEN}}',
    'Client-Id'     : '{{CLIENT_ID}}'
}
parameters = {
    'broadcaster_id' : '{{USER_ID}}'
}
# Defining the body parameters
payload = {
    'tag_ids' : [
        '621fb5bf-5498-4d8f-b4ac-db4d40d401bf',     # 1 Credit Clear
        '52d7e4cc-633d-46f5-818c-bb59102d9549'      # Vtuber
    ]
}
response = requests.put('https://api.twitch.tv/helix/streams/tags',
                        headers=headers, params=parameters, json=payload)
print(response.status_code)

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.