Goals - API Reference | Twitch Developers

Get Creator Goals

Gets the broadcaster's list of active goals. Use this endpoint to get the current progress of each goal.

Instead of polling for the progress of a goal, consider subscribing to receive notifications when a goal makes progress using the channel.goal.progress subscription type. Read More

Endpoint

GEThttps://api.twitch.tv/helix/goals

Authorization

Requires one of the following:

A user access token that includes the channel:read:goals scope.

Query Parameters

broadcaster_idStringRequired
The ID of the broadcaster that created the goals. This ID must match the user ID in the user access token.

Response Body

dataObject[]
The list of goals. The list is empty if the broadcaster hasn't created goals.
Hide child attributesShow child attributes
- data.idString
  An ID that identifies this goal.
- data.broadcaster_idString
  An ID that identifies the broadcaster that created the goal.
- data.broadcaster_nameString
  The broadcaster's display name.
- data.broadcaster_loginString
  The broadcaster's login name.
- data.typeString
  The type of goal.
  Possible values
  - follower
    The goal is to increase followers.
  - subscription
    The goal is to increase subscriptions. This type shows the net increase or decrease in tier points associated with the subscriptions.
  - subscription_count
    The goal is to increase subscriptions. This type shows the net increase or decrease in the number of subscriptions.
  - new_subscription
    The goal is to increase subscriptions. This type shows only the net increase in tier points associated with the subscriptions (it does not account for users that unsubscribed since the goal started).
  - new_subscription_count
    The goal is to increase subscriptions. This type shows only the net increase in the number of subscriptions (it does not account for users that unsubscribed since the goal started).
  - new_bit
    The goal is to increase the amount of Bits used on the channel.
  - new_cheerer
    The goal is to increase the amount of unique Cheerers on to Cheer on the channel.
- data.descriptionString
  A description of the goal. Is an empty string if not specified.
- data.current_amountInteger
  The goal's current value.
  
  The goal's 'type' determines how this value is increased or decreased.
  - If 'type' is follower, this field is set to the broadcaster's current number of followers. This number increases with new followers and decreases when users unfollow the broadcaster.
  - If 'type' is subscription, this field is increased and decreased by the points value associated with the subscription tier. For example, if a tier-two subscription is worth 2 points, this field is increased or decreased by 2, not 1.
  - If 'type' is subscription_count, this field is increased by 1 for each new subscription and decreased by 1 for each user that unsubscribes.
  - If 'type' is new_subscription, this field is increased by the points value associated with the subscription tier. For example, if a tier-two subscription is worth 2 points, this field is increased by 2, not 1.
  - If 'type' is new_subscription_count, this field is increased by 1 for each new subscription.
  - If 'type' is new_bit, this field is increased by the number of Bits used on the channel.
  - If 'type' is new_cheerer, this field is increased by 1 the first time each user Cheers on the channel after the goal starts. Other ways of using Bits don't count.
- data.target_amountInteger
  The goal's target value. For example, if the broadcaster has 200 followers before creating the goal, and their goal is to double that number, this field is set to 400.
- data.created_atString
  The UTC date and time (in RFC3339 format) that the broadcaster created the goal.

Response Codes

200OK: Successfully retrieved the broadcaster's goals.
400Bad Request: The broadcaster_id query parameter is required.
The ID in the broadcaster_id query parameter is not valid.
401Unauthorized: The Authorization header is required and must contain a user access token.
The user access token must include the channel:read:goals scope.
The ID in broadcaster_id must match the user ID in the user access token.
The access token is not valid.
The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Request Example

curl -X GET 'https://api.twitch.tv/helix/goals?broadcaster_id=141981764' \
  -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/goals?broadcaster_id=141981764" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/goals?broadcaster_id=141981764", {
  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/goals",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    params={
        "broadcaster_id": "141981764",
    },
)

data = response.json()

req, _ := http.NewRequest("GET", "https://api.twitch.tv/helix/goals?broadcaster_id=141981764", 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/goals?broadcaster_id=141981764");

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/goals?broadcaster_id=141981764");
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/goals?broadcaster_id=141981764")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

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

Response Example

{
  "data": [
    {
      "id": "1woowvbkiNv8BRxEWSqmQz6Zk92",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "type": "follower",
      "description": "Follow goal for Helix testing",
      "current_amount": 27062,
      "target_amount": 30000,
      "created_at": "2021-08-16T17:22:23Z"
    }
  ]
}