Skip to main content
GET
/
twitch
/
badges
/
channel
curl "https://teambattles.gg/api/v1/twitch/badges/channel?username=ninja" \
  -H "Authorization: Bearer tb_your_api_key"

{
  "broadcaster_id": "<string>",
  "broadcaster_name": "<string>",
  "badges": [
    {
      "set_id": "<string>",
      "versions": [
        {
          "id": "<string>",
          "image_url_1x": "<string>",
          "image_url_2x": "<string>",
          "image_url_4x": "<string>",
          "title": "<string>",
          "description": "<string>",
          "click_action": "<string>",
          "click_url": "<string>"
        }
      ]
    }
  ],
  "timestamp": "2023-11-07T05:31:56Z"
}
curl "https://teambattles.gg/api/v1/twitch/badges/channel?username=ninja" \
  -H "Authorization: Bearer tb_your_api_key"

​
Prerequisites

This endpoint requires:
  1. The connections.twitch permission enabled on your API key
  2. A Twitch account connected to your TeamBattles account

​
Channel Identification

You must provide exactly one of these parameters:
ParameterDescriptionExample
usernameTwitch channel usernameninja
idTwitch broadcaster ID123456789
Using id is more stable since usernames can change. However, username is more user-friendly for manual testing.

​
What Are Channel Badges?

Channel badges are custom badges specific to a Twitch channel:
  • Subscriber badges - Tiered badges (Tier 1, 2, 3) with custom artwork
  • Subscriber tenure badges - Special badges for long-term subscribers (3, 6, 12+ months)
  • Bits badges - Badges for users who’ve cheered bits
  • Custom channel badges - Any other channel-specific badges

​
Badge Resolution

When displaying chat badges, use this priority:
  1. Channel badges (this endpoint) - Check if the channel has a custom badge
  2. Global badges (Get Global Badges) - Fall back to global badges
For example, a channel might have custom subscriber badges. If the set_id is subscriber, use the channel’s custom images. For moderator, use the global badge.

​
Caching

The response includes a Cache-Control: public, max-age=3600 header. Channel badges can change when streamers update their artwork, but caching for 1 hour is generally safe.

​
Example Response

{
  "broadcaster_id": "123456789",
  "broadcaster_name": "Ninja",
  "badges": [
    {
      "set_id": "subscriber",
      "versions": [
        {
          "id": "0",
          "image_url_1x": "https://static-cdn.jtvnw.net/.../1",
          "image_url_2x": "https://static-cdn.jtvnw.net/.../2",
          "image_url_4x": "https://static-cdn.jtvnw.net/.../3",
          "title": "Subscriber",
          "description": "Subscriber badge"
        },
        {
          "id": "2000",
          "image_url_1x": "https://static-cdn.jtvnw.net/.../1",
          "image_url_2x": "https://static-cdn.jtvnw.net/.../2",
          "image_url_4x": "https://static-cdn.jtvnw.net/.../3",
          "title": "Tier 2 Subscriber",
          "description": "Tier 2 subscriber badge"
        }
      ]
    },
    {
      "set_id": "bits",
      "versions": [
        {
          "id": "1",
          "title": "1 Bit",
          "description": "Cheered 1 bit"
        }
      ]
    }
  ],
  "timestamp": "2026-01-23T12:00:00.000Z"
}

Authorizations

​
Authorization
string
header
required

API key authentication. Generate an API key from Settings > Developer in the TeamBattles app. Format: tb_xxxxxxxx...

Query Parameters

​
username
string

Twitch channel username (e.g., 'ninja'). Mutually exclusive with id.

​
id
string

Twitch broadcaster ID. Mutually exclusive with username.

Response

Successful response

​
broadcaster_id
string

Twitch broadcaster ID

​
broadcaster_name
string

Twitch display name

​
badges
object[]
​
timestamp
string<date-time>

Response timestamp (ISO 8601)