Hype Train - API Reference | Twitch Developers

Get Hype Train Status

Get the status of a Hype Train for the specified broadcaster.

Endpoint

GEThttps://api.twitch.tv/helix/hypetrain/status

Authorization

Requires one of the following:

A user access token that includes the channel:read:hype_train scope.The User ID associated with the token must match the broadcaster_id in the query parameter.

Query Parameters

broadcaster_idStringRequired
The User ID of the channel broadcaster.

Response Body

dataObject[]
A list that contains information related to the channel's Hype Train.
Hide child attributesShow child attributes
- data.currentObject
  An object describing the current Hype Train. Null if a Hype Train is not active.
  Hide child attributesShow child attributes
  - data.current.idString
    The Hype Train ID.
  - data.current.broadcaster_user_idString
    The broadcaster ID.
  - data.current.broadcaster_user_loginString
    The broadcaster login.
  - data.current.broadcaster_user_nameString
    The broadcaster display name.
  - data.current.levelInteger
    The current level of the Hype Train.
  - data.current.totalInteger
    Total points contributed to the Hype Train.
  - data.current.progressInteger
    The number of points contributed to the Hype Train at the current level.
  - data.current.goalInteger
    The number of points required to reach the next level.
  - data.current.top_contributionsObject[]
    The contributors with the most points contributed.
    Hide child attributesShow child attributes
    data.current.top_contributions.user_idString
    The ID of the user that made the contribution.
    data.current.top_contributions.user_loginString
    The user's login name.
    data.current.top_contributions.user_nameString
    The user's display name.
    data.current.top_contributions.typeString
    The contribution method used.
    Possible values
    bits
    Cheering with Bits.
    subscription
    Subscription activity like subscribing or gifting subscriptions.
    other
    Covers other contribution methods not listed.
    data.current.top_contributions.totalInteger
    The total number of points contributed for the type.
  - data.current.shared_train_participantsObject[]
    A list containing the broadcasters participating in the shared Hype Train. Null if the Hype Train is not shared.
    Hide child attributesShow child attributes
    data.current.shared_train_participants.broadcaster_user_idString
    The broadcaster ID.
    data.current.shared_train_participants.broadcaster_user_loginString
    The broadcaster login.
    data.current.shared_train_participants.broadcaster_user_nameString
    The broadcaster display name.
  - data.current.started_atString
    The time when the Hype Train started.
  - data.current.expires_atString
    The time when the Hype Train expires. The expiration is extended when the Hype Train reaches a new level.
  - data.current.typeString
    The type of the Hype Train.
    Possible values
    treasure
    golden_kappa
    regular
  - data.current.is_shared_trainBoolean
    Indicates if the Hype Train is shared. When true, shared_train_participants will contain the list of broadcasters the train is shared with.
- data.all_time_highObject
  An object with information about the channel's Hype Train records. Null if a Hype Train has not occurred.
  Hide child attributesShow child attributes
  - data.all_time_high.levelInteger
    The level of the record Hype Train.
  - data.all_time_high.totalInteger
    Total points contributed to the record Hype Train.
  - data.all_time_high.achieved_atString
    The time when the record was achieved.
- data.shared_all_time_highObject
  An object with information about the channel's shared Hype Train records. Null if the channel hasn't taken part in a shared Hype Train.
  Hide child attributesShow child attributes
  - data.shared_all_time_high.levelInteger
    The level of the record Hype Train.
  - data.shared_all_time_high.totalInteger
    Total points contributed to the record Hype Train.
  - data.shared_all_time_high.achieved_atString
    The time when the record was achieved.

Response Codes

200OK: Successfully retrieved the status object.
400Bad Request: The ID in the broadcaster_id query parameter is not valid.
401Unauthorized: The OAuth token is not valid.
The Authorization header is required and must contain a user access token.
The user access token must include the channel:read:hype_train scope.
The ID in broadcaster_id must match the user ID in the user access token.
500Internal Error: Internal Server Error.

Request Example

curl -X GET 'https://api.twitch.tv/helix/hypetrain/status?broadcaster_id=123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/hypetrain/status?broadcaster_id=123" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/hypetrain/status?broadcaster_id=123", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
  },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.twitch.tv/helix/hypetrain/status",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    params={
        "broadcaster_id": "123",
    },
)

data = response.json()

req, _ := http.NewRequest("GET", "https://api.twitch.tv/helix/hypetrain/status?broadcaster_id=123", nil)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/hypetrain/status?broadcaster_id=123");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
]);

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.twitch.tv/helix/hypetrain/status?broadcaster_id=123");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .get("https://api.twitch.tv/helix/hypetrain/status?broadcaster_id=123")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

let data = response.text().await?;

Response Example

{
  "data": [
    {
      "current": {
        "id": "1b0AsbInCHZW2SQFQkCzqN07Ib2",
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "level": 2,
        "total": 700,
        "progress": 200,
        "goal": 1000,
        "top_contributions": [
          {
            "user_id": "123",
            "user_login": "pogchamp",
            "user_name": "PogChamp",
            "type": "bits",
            "total": 50
          },
          {
            "user_id": "456",
            "user_login": "kappa",
            "user_name": "Kappa",
            "type": "subscription",
            "total": 45
          }
        ],
        "shared_train_participants": [
          {
            "broadcaster_user_id": "456",
            "broadcaster_user_login": "pogchamp",
            "broadcaster_user_name": "PogChamp"
          },
          {
            "broadcaster_user_id": "321",
            "broadcaster_user_login": "pogchamp",
            "broadcaster_user_name": "PogChamp"
          }
        ],
        "started_at": "2020-07-15T17:16:03.17106713Z",
        "expires_at": "2020-07-15T17:16:11.17106713Z",
        "type": "golden_kappa",
        "is_shared_train": true
      },
      "all_time_high": {
        "level": 6,
        "total": 2850,
        "achieved_at": "2020-04-24T20:12:21.003802269Z"
      },
      "shared_all_time_high": {
        "level": 16,
        "total": 23850,
        "achieved_at": "2020-04-27T20:12:21.003802269Z"
      }
    }
  ]
}