Subscriptions - API Reference | Twitch Developers

Get Broadcaster Subscriptions

Gets a list of users that subscribe to the specified broadcaster.

Endpoint

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

Authorization

Requires one of the following:

A user access token that includes the channel:read:subscriptions scope.
An app access token.Only accessible to Twitch Extensions. The broadcaster must have granted the channel:read:subscriptions scope from within the Twitch Extensions manager.

Query Parameters

broadcaster_idStringRequired
The broadcaster's ID. This ID must match the user ID in the access token.
user_idString
Filters the list to include only the specified subscribers. To specify more than one subscriber, include this parameter for each subscriber. For example, '&user_id=1234&user_id=5678'. You may specify a maximum of 100 subscribers.
firstInteger
The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
afterString
The cursor used to get the next page of results. Do not specify if you set the user_id query parameter. The Pagination object in the response contains the cursor's value. Read More
beforeString
The cursor used to get the previous page of results. Do not specify if you set the user_id query parameter. The Pagination object in the response contains the cursor's value. Read More

Response Body

dataObject[]
The list of users that subscribe to the broadcaster. The list is empty if the broadcaster has no subscribers. Some subscriptions aren't included, such as those from users whose accounts no longer exist, so a page may contain fewer than first items, or none, and still contain a cursor.
Hide child attributesShow child attributes
- data.broadcaster_idString
  An ID that identifies the broadcaster.
- data.broadcaster_loginString
  The broadcaster's login name.
- data.broadcaster_nameString
  The broadcaster's display name.
- data.gifter_idString
  The ID of the user that gifted the subscription to the user. Is an empty string if 'is_gift' is false. For an anonymous gift, the ID is 274598607, which identifies the ananonymousgifter account.
- data.gifter_loginString
  The gifter's login name. Is an empty string if 'is_gift' is false.
- data.gifter_nameString
  The gifter's display name. Is an empty string if 'is_gift' is false.
- data.is_giftBoolean
  A Boolean value that determines whether the subscription is a gift subscription. Is true if the subscription was gifted.
- data.plan_nameString
  The name of the subscription.
- data.tierString
  The type of subscription.
  Possible values
  - 1000
    Tier 1
  - 2000
    Tier 2
  - 3000
    Tier 3
- data.user_idString
  An ID that identifies the subscribing user.
- data.user_nameString
  The user's display name.
- data.user_loginString
  The user's login name.
paginationObject
Contains the information used to page through the list of results. The object contains a cursor even on the last page of subscriptions; using that cursor returns no subscriptions and an empty object. The response doesn't include this object if you specify the user_id query parameter. Read More
Hide child attributesShow child attributes
- pagination.cursorString
  The cursor used to get the next or previous page of results. Use the cursor to set the request's after or before query parameter depending on whether you're paging forwards or backwards.
pointsInteger
The current number of subscriber points earned by this broadcaster. Points are based on the subscription tier of each user that subscribes to this broadcaster. For example, a Tier 1 subscription is worth 1 point, Tier 2 is worth 2 points, and Tier 3 is worth 6 points. The number of points determines the number of emote slots that are unlocked for the broadcaster (see Subscriber Emote Slots).

The response doesn't include this field if you specify the user_id query parameter.
totalInteger
The total number of users that subscribe to this broadcaster. The response doesn't include this field if you specify the user_id query parameter.

Response Codes

200OK: Successfully retrieved the broadcaster's list of subscribers.
400Bad Request: The broadcaster_id query parameter is required.
The request may specify either the before or after query parameter but not both.
The cursor specified in the before or after query parameter is not valid.
401Unauthorized: The ID in broadcaster_id must match the user ID found in the request's OAuth token.
The Authorization header is required and must contain a user access token.
The user access token must include the channel:read:subscriptions scope.
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/subscriptions?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/subscriptions?broadcaster_id=141981764" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/subscriptions?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/subscriptions",
    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/subscriptions?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/subscriptions?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/subscriptions?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/subscriptions?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": [
    {
      "broadcaster_id": "141981764",
      "broadcaster_login": "twitchdev",
      "broadcaster_name": "TwitchDev",
      "gifter_id": "12826",
      "gifter_login": "twitch",
      "gifter_name": "Twitch",
      "is_gift": true,
      "tier": "1000",
      "plan_name": "Channel Subscription (twitchdev)",
      "user_id": "527115020",
      "user_name": "twitchgaming",
      "user_login": "twitchgaming"
    },
    ...
  ],
  "pagination": {
    "cursor": "xxxx"
  },
  "total": 13,
  "points": 13
}

Check User Subscription

Checks whether the user subscribes to the broadcaster's channel.