Twitch API Reference
| Resource | Endpoint | Description |
|---|---|---|
| Ads | Start Commercial | Starts a commercial on a specified channel. |
| Analytics | Get Extension Analytics | Gets a URL that Extension developers can use to download analytics reports (CSV files) for their Extensions. The URL is valid for 5 minutes. For details about analytics and the fields returned, see the Insights & Analytics guide. |
| Analytics | Get Game Analytics | Gets a URL that game developers can use to download analytics reports (CSV files) for their games. The URL is valid for 5 minutes. |
| Bits | Get Bits Leaderboard | Gets a ranked list of Bits leaderboard information for an authorized broadcaster. |
| Bits | Get Cheermotes | Retrieves the list of available Cheermotes, animated emotes to which viewers can assign Bits, to cheer in chat. Cheermotes returned are available throughout Twitch, in all Bits-enabled channels. |
| Bits | Get Extension Transactions | Get Extension Transactions allows extension back end servers to fetch a list of transactions that have occurred for their extension across all of Twitch. |
| Channels | Get Channel Information | Gets channel information for users. |
| Channels | Modify Channel Information | Modifies channel information for users. |
| Channels | Get Channel Editors | Gets a list of users who have editor permissions for a specific channel. |
| Channel Points | Create Custom Rewards | Creates a Custom Reward on a channel.
|
| Channel Points | Delete Custom Reward | Deletes a Custom Reward on a channel. |
| Channel Points | Get Custom Reward | Returns a list of Custom Reward objects for the Custom Rewards on a channel. |
| Channel Points | Get Custom Reward Redemption | Returns Custom Reward Redemption objects for a Custom Reward on a channel that was created by the same |
| Channel Points | Update Custom Reward | Updates a Custom Reward created on a channel. |
| Channel Points | Update Redemption Status | Updates the status of Custom Reward Redemption objects on a channel that are in the UNFULFILLED status. |
| Chat | Get Channel Emotes | NEW Gets all custom emotes for a specific Twitch channel including subscriber emotes and Bits tier emotes. Custom channel emotes are custom emoticons that viewers may use in Twitch chat once they are subscribed to, cheered in, or followed the channel that owns the emotes. |
| Chat | Get Global Emotes | NEW Gets all global emotes. Global emotes are Twitch-specific emoticons that every user can use in Twitch chat. |
| Chat | Get Emote Sets | NEW Gets all Twitch emotes for one or more specific emote sets. |
| Chat | Get Channel Chat Badges | NEW Gets a list of custom chat badges that can be used in chat for the specified channel. |
| Chat | Get Global Chat Badges | NEW Gets a list of chat badges that can be used in chat for any channel. |
| Clips | Create Clip | Creates a clip programmatically. This returns both an ID and an edit URL for the new clip. |
| Clips | Get Clips | Gets clip information by clip ID (one or more), broadcaster ID (one only), or game ID (one only). |
| Entitlements | Get Code Status |
Gets the status of one or more provided codes. This API requires that the caller is an authenticated Twitch user. The API is throttled to one request per second per authenticated user. |
| Entitlements | Get Drops Entitlements | Gets a list of entitlements for a given organization that have been granted to a game, user, or both. |
| Entitlements | Redeem Code | Redeems one or more provided codes to the authenticated Twitch user. This API requires that the caller is an authenticated Twitch user. This API requires that the caller is an authenticated Twitch user. The API is throttled to one request per second per authenticated user. |
| EventSub | Create EventSub Subscription | Creates an EventSub subscription. |
| EventSub | Delete EventSub Subscription | Delete an EventSub subscription. |
| EventSub | Get EventSub Subscriptions | Get a list of your EventSub subscriptions. The subscriptions are paginated and ordered by most recent first. |
| Games | Get Top Games | Gets games sorted by number of current viewers on Twitch, most popular first. |
| Games | Get Games | Gets game information by game ID or name. |
| Hype Train | Get Hype Train Events | Gets the information of the most recent Hype Train of the given channel ID. |
| Moderation | Check AutoMod Status | Determines whether a string message meets the channel’s AutoMod requirements. |
| Moderation | Manage Held AutoMod Messages | Allow or deny a message that was held for review by AutoMod. |
| Moderation | Get Banned Events | Returns all user bans and un-bans in a channel. |
| Moderation | Get Banned Users | Returns all banned and timed-out users in a channel. |
| Moderation | Get Moderators | Returns all moderators in a channel. |
| Moderation | Get Moderator Events | Returns a list of moderators or users added and removed as moderators from a channel. |
| Polls | Get Polls | NEW Get information about all polls or specific polls for a Twitch channel. Poll information is available for 90 days. |
| Polls | Create Poll | NEW Create a poll for a specific Twitch channel. |
| Polls | End Poll | NEW End a poll that is currently active. |
| Predictions | Get Predictions | NEW Get information about all Channel Points Predictions or specific Channel Points Predictions for a Twitch channel. |
| Predictions | Create Prediction | NEW Create a Channel Points Prediction for a specific Twitch channel. |
| Predictions | End Prediction | NEW Lock, resolve, or cancel a Channel Points Prediction. |
| Schedule | Get Channel Stream Schedule | NEW Gets all scheduled broadcasts or specific scheduled broadcasts from a channel’s stream schedule. |
| Schedule | Get Channel iCalendar | NEW Gets all scheduled broadcasts from a channel’s stream schedule as an iCalendar. |
| Schedule | Update Channel Stream Schedule | NEW Update the settings for a channel’s stream schedule. |
| Schedule | Create Channel Stream Schedule Segment | NEW Create a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule. |
| Schedule | Update Channel Stream Schedule Segment | NEW Update a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule. |
| Schedule | Delete Channel Stream Schedule Segment | NEW Delete a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule. |
| Search | Search Categories | Returns a list of games or categories that match the query via name either entirely or partially. |
| Search | Search Channels | Returns a list of channels that match the query via channel name or description either entirely or partially. |
| Streams | Get Stream Key | Gets the channel stream key for a user. |
| Streams | Get Streams | Gets information about active streams. Streams are returned sorted by number of current viewers, in descending order. |
| Streams | Get Followed Streams | Gets information about active streams belonging to channels that the authenticated user follows. |
| Streams | Create Stream Marker | Creates a marker in the stream of a user specified by user ID. A marker is an arbitrary point in a stream that the broadcaster wants to mark. |
| Streams | Get Stream Markers | Gets a list of markers for either a specified user’s most recent stream or a specified VOD/video (stream), ordered by recency. A marker is an arbitrary point in a stream that the broadcaster wants to mark. |
| Subscriptions | Get Broadcaster Subscriptions | Gets all of a broadcaster’s subscriptions. |
| Subscriptions | Check User Subscription | Checks if a specific user is subscribed to a specific channel. |
| Tags | Get All Stream Tags | Gets the list of all stream tags defined by Twitch, optionally filtered by tag ID(s). |
| Tags | Get Stream Tags | Gets the list of current stream tags that have been set for a channel. |
| Tags | Replace Stream Tags | Applies specified tags to a specified stream, overwriting any existing tags applied to that stream. |
| Teams | Get Channel Teams | Retrieves a list of Twitch Teams of which the specified channel/broadcaster is a member. |
| Teams | Get Teams | Gets information for a specific Twitch Team. |
| Users | Get Users | Gets information about one or more specified Twitch users. Users are identified by optional user IDs and/or login name. |
| Users | Update User | Updates the description of a user specified by a Bearer token. |
| Users | Get Users Follows | Gets information on follow relationships between two Twitch users. Information returned is sorted in order, most recent follow first. |
| Users | Create User Follows | Adds a specified user to the followers of a specified channel. |
| Users | Delete User Follows | Deletes a specified user from the followers of a specified channel. |
| Users | Get User Block List | Gets a specified user’s block list. The list is sorted by when the block occurred in descending order (i.e. most recent block first). |
| Users | Block User | Blocks the specified user on behalf of the authenticated user. |
| Users | Unblock User | Unblocks the specified user on behalf of the authenticated user. |
| Users | Get User Extensions | Gets a list of all extensions (both active and inactive) for a specified user, identified by a Bearer token. |
| Users | Get User Active Extensions | Gets information about active extensions installed by a specified user, identified by a user ID or Bearer token. |
| Users | Update User Extensions | Updates the activation state, extension ID, and/or version number of installed extensions for a specified user, identified by a Bearer token. |
| Videos | Get Videos | Gets video information by one or more video IDs, user ID, or game ID. |
| Videos | Delete Videos | Deletes one or more videos. Videos are past broadcasts, Highlights, or uploads. |
| Webhooks | Get Webhook Subscriptions | Gets the Webhook subscriptions of an application identified by a Bearer token, in order of expiration. |
Start Commercial
✎Starts a commercial on a specified channel.
Authentication
- OAuth Token required
- Required scope:
channel:edit:commercial
Pagination Support
None
URL
POST https://api.twitch.tv/helix/channels/commercial
Required Query Parameter
None
Required Body Parameter
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | ID of the channel requesting a commercial Minimum: 1 Maximum: 1 |
length |
integer | Desired length of the commercial in seconds. Valid options are 30, 60, 90, 120, 150, 180. |
Optional Query Parameters
None
Response Fields
| Parameter | Type | Description |
|---|---|---|
length |
integer | Length of the triggered commercial |
message |
string | Provides contextual information on why the request failed |
retry_after |
integer | Seconds until the next commercial can be served on this channel |
Example Request
This request starts a commercial.
curl -X POST 'https://api.twitch.tv/helix/channels/commercial' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
--data-raw '{
"broadcaster_id": "41245072",
"length": 60
}'
Example Response
{
"data": [{
"length" : 60,
"message" : "",
"retry_after" : 480
}]
}
Get Extension Analytics
✎Gets a URL that Extension developers can use to download analytics reports (CSV files) for their Extensions. The URL is valid for 5 minutes.
If you specify a future date, the response will be “Report Not Found For Date Range.” If you leave both started_at and ended_at blank, the API returns the most recent date of data.
Authentication
- OAuth token required
- Required scope:
analytics:read:extensions
URL
GET https://api.twitch.tv/helix/analytics/extensions
Required Query Parameters
None
Optional Query Parameters
| Name | Type | Description |
|---|---|---|
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries without extension_id. If an extension_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query. |
ended_at |
string | Ending date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z. The report covers the entire ending date; e.g., if 2018-05-01T00:00:00Z is specified, the report covers up to 2018-05-01T23:59:59Z.If this is provided, started_at also must be specified. If ended_at is later than the default end date, the default date is used. Default: 1-2 days before the request was issued (depending on report availability). |
extension_id |
string | Client ID value assigned to the extension when it is created. If this is specified, the returned URL points to an analytics report for just the specified extension. If this is not specified, the response includes multiple URLs (paginated), pointing to separate analytics reports for each of the authenticated user’s Extensions. |
first |
integer | Maximum number of objects to return. Maximum: 100. Default: 20. |
started_at |
string | Starting date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z. This must be on or after January 31, 2018.If this is provided, ended_at also must be specified. If started_at is earlier than the default start date, the default date is used. The file contains one row of data per day. |
type |
string | Type of analytics report that is returned. Currently, this field has no affect on the response as there is only one report type. If additional types were added, using this field would return only the URL for the specified report. Limit: 1. Valid values: "overview_v2". |
Response Fields
| Field | Type | Description |
|---|---|---|
ended_at | string | Report end date/time. |
extension_id | string | ID of the extension whose analytics data is being provided. |
pagination | object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. This is returned only if extension_id is not specified in the request. |
started_at | string | Report start date/time. Note this may differ from (be later than) the started_at value in the request; the response value is the date when data for the extension is available. |
type | string | Type of report. |
URL | string | URL to the downloadable CSV file containing analytics data. Valid for 5 minutes. |
Example Request #1
This gets the URLs for all reports for all Extensions of the authenticated client. For the purpose of this example, assume the request is issued on June 1, 2018.
curl -X GET 'https://api.twitch.tv/helix/analytics/extensions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response #1
{
"data": [
{
"extension_id": "efgh",
"URL": "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/dynamic/LoL%20ADC_overview_v2_2018-03-01_2018-06-01_8a879932-8e70-7a4c-2b97-e0eaba28c3b0.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAI7LOPgTrAIVYE6KQ%2F20180731%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180731T202847Z&X-Amz-Expires=60&X-Amz-Security-Token=FQoDYXdzEDMaDObdwyOVISdo6feHSSK3A9R9gMFeS5frG5Dsr4k4tJemqCIazhsQJrpsehBoOufaQkCxrb8RD3oU0xC5pWrZe9kN%2BnezIoLOgTtFRAqTzdIr7J5iUOxGFyKN9XmrmUHGexFfALvoPQWUJNbxoFU6shajSmO3sPK2GnuEaGmIrAqjKrim8saLHDV%2FdSi2ZH3fFx6sBQEGv13Lx0zua7AsvaL%2BSfhIAcOazWjYLMU5N9bxXmaN7IAIF4UjNPqbg07RMWW70hm0edH0RPi%2Fw00faeeSvmreHq6c1C1Lu8a7AysMb0pEGBT7VxmuGmWsXyjLWZ6oNgbx88HXoMJpmAn5Y1hUu7VzOaa84T%2BmCF5Sbn7hbB1xIiPdzaVQ%2Bd85sy4ln09h7dgKh6GFE1VTas2v7RJU1lyD%2FZ%2FWKBwV5Ol8GEGrF1pme8mSBpPGUAJ4vxjLmrGL7ctty%2F0vXke3PyD%2B4%2FtHZ67xaw0y8EKrau23Xvt3blkcDNoQYOfcS%2FqbaK%2BHpyVq4bIBtQq%2BHYU5MuFkgEuwSe5zPDle1ysKSN11B6B6Sy7Httrq542OONS%2BfURkczMbKSPEShddN32Y9VUqKYdUo%2FsWVQQoy7uC2wU%3D&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3Bfilename%3D%22WoW%20Armory_overview_v1_2018-04-30_2018-06-01.csv%22&X-Amz-Signature=eb7721e40cbfd1d7409887dae3792cdb2add025ace953a63ba8e3545b92ae058",
"type": "overview_v2",
"date_range": {
"started_at": "2018-03-01T00:00:00Z",
"ended_at": "2018-06-01T00:00:00Z"
}
},
...
],
"pagination": {"cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"}
}
Get Game Analytics
✎Gets a URL that game developers can use to download analytics reports (CSV files) for their games. The URL is valid for 5 minutes. For detail about analytics and the fields returned, see the Insights & Analytics guide.
The response has a JSON payload with a data field containing an array of games information elements and can contain a pagination field containing information required to query for more streams.
If you specify a future date, the response will be “Report Not Found For Date Range.” If you leave both started_at and ended_at blank, the API returns the most recent date of data.
Authentication
- OAuth token required
- Required scope:
analytics:read:games
URL
GET https://api.twitch.tv/helix/analytics/games
Required Query Parameters
None
Optional Query Parameters
| Name | Type | Description |
|---|---|---|
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries without game_id. If a game_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query. |
ended_at |
string | Ending date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z. The report covers the entire ending date; e.g., if 2018-05-01T00:00:00Z is specified, the report covers up to 2018-05-01T23:59:59Z.If this is provided, started_at also must be specified. If ended_at is later than the default end date, the default date is used. Default: 1-2 days before the request was issued (depending on report availability). |
first |
integer | Maximum number of objects to return. Maximum: 100. Default: 20. |
game_id |
string | Game ID. If this is specified, the returned URL points to an analytics report for just the specified game. If this is not specified, the response includes multiple URLs (paginated), pointing to separate analytics reports for each of the authenticated user’s games. |
started_at |
string | Starting date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z.If this is provided, ended_at also must be specified. If started_at is earlier than the default start date, the default date is used. Default: 365 days before the report was issued. The file contains one row of data per day. |
type |
string | Type of analytics report that is returned. Currently, this field has no affect on the response as there is only one report type. If additional types were added, using this field would return only the URL for the specified report. Limit: 1. Valid values: "overview_v2". |
Response Fields
| Field | Type | Description |
|---|---|---|
ended_at |
string | Report end date/time. |
game_id |
string | ID of the game whose analytics data is being provided. |
pagination |
Object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. This is returned only if game_id is not specified in the request. |
started_at |
string | Report start date/time. |
type |
string | Type of report. |
URL |
string | URL to the downloadable CSV file containing analytics data. Valid for 5 minutes. |
Example Request #1
This gets the URL for a downloadable CSV report for game ID 493057, covering the period January 1, 2018 to March 1, 2018.
curl -X GET 'https://api.twitch.tv/helix/analytics/games?game_id=493057&started_at=2018-01-01T00:00:00Z&ended_at=2018-03-01T00:00:00Z' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response #1
{
"data": [
{
"game_id" : "493057",
"URL" : "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/games/66170/overview/1518307200000.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAJP7WFIAF26K7BC2Q%2F20180222%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180222T220651Z&X-Amz-Expires=60&X-Amz-Security-Token=FQoDYXdzEE0aDLKNl9aCgfuikMKI%2ByK3A4e%2FR%2B4to%2BmRZFUuslNKs%2FOxKeySB%2BAU87PBtNGCxQaQuN2Q8KI4Vg%2Bve2x5eenZdoH0ZM7uviM94sf2GlbE9Z0%2FoJRmNGNhlU3Ua%2FupzvByCoMdefrU8Ziiz4j8EJCgg0M1j2aF9f8bTC%2BRYwcpP0kjaZooJS6RFY1TTkh659KBA%2By%2BICdpVK0fxOlrQ%2FfZ6vIYVFzvywBM05EGWX%2F3flCIW%2BuZ9ZxMAvxcY4C77cOLQ0OvY5g%2F7tuuGSO6nvm9Eb8MeMEzSYPr4emr3zIjxx%2Fu0li9wjcF4qKvdmnyk2Bnd2mepX5z%2BVejtIGBzfpk%2Fe%2FMqpMrcONynKoL6BNxxDL4ITo5yvVzs1x7OumONHcsvrTQsd6aGNQ0E3lrWxcujBAmXmx8n7Qnk4pZnHZLgcBQam1fIGba65Gf5Ern71TwfRUsolxnyIXyHsKhd2jSmXSju8jH3iohjv99a2vGaxSg8SBCrQZ06Bi0pr%2FTiSC52U1g%2BlhXYttdJB4GUdOvaxR8n6PwMS7HuAtDJUui8GKWK%2F9t4OON3qhF2cBt%2BnV%2BDg8bDMZkQ%2FAt5blvIlg6rrlCu0cYko4ojb281AU%3D&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3Bfilename%3DWarframe-overview-2018-02-11.csv&X-Amz-Signature=49cc07cbd9d753b00315b66f49b9e4788570062ff3bd956288ab4f164cf96708",
"type" : "overview_v2",
"date_range" : {
"started_at" : "2018-01-01T00:00:00Z",
"ended_at" : "2018-03-01T00:00:00Z"
}
}
]
}
Example Request #2
This gets the first 5 URLs (paginated) for all reports for all games of the authenticated client. The request is issued on June 14, 2018.
curl -X GET 'https://api.twitch.tv/helix/analytics/games?first=5' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response #2
{
"data": [
{
"game_id": "9821",
"URL": "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/games/9821/overview/1526428800000.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAJQ4MLJCNPIYDOZ4Q%2F20180517%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180517T231129Z&X-Amz-Expires=60&X-Amz-Security-Token=FQoDYXdzEK7%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDD0JCM06UswayN4iVyK3AzIiwI0Qf4KRs2yk9nCiocQOwmMWa7FPJnJEd%2FIxljnmZy%2BphQEEWN3%2Bt8k06wZysfPHvW71zcrIeclv11kNtXaYojC%2FHVKJWO8EnicIQE73kokr16fkf1Q4eglQBuu56jJQoTsEn2UkgZff9XHx69LyFvLYf33ue10CjeJE1bY65%2B6LtcPKciJK%2FNRS1TyUsz%2FiQjyxMEUpAKm39HxNtNKFM5xehjAoWC1KfJc52XVQGFO%2Fm2EQiJj6RoifNkiIQKb4m7nGr86zvIQKDQcxcpVbiGNEcC8UugZgCnuspSPjuJLARb%2BNT%2FjLKopd2%2FUKDlIY%2BAoyEk%2B%2FGIWL5TgvjjmT5uaJ5AcnTm4b7DlV%2FkmDsYHFQez0Mu4%2BwoujZEqR0K%2BtDSyAvva2nUUGabZuDeaaiQD4JfrokXC5GWtninHQCAoPiC4q%2FMYkHS82wxPjJp0l4cStwzEDQ5LJ4cehKm4tCoY1m1whWIJsNuyfLtIUH2rBTuF9D5DFmsmpXiKc4LE9saQgSlLwNBEGASqAbRuy7Tc2ZlcIp1lBllioxhoYL3XcjaXOX3qluWGMwgXdV2Odq0L03MkoxuL31wU%3D&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3Bfilename%3D%22Heroes%20of%20Might%20and%20Magic%20IV-overview_v1-2018-05-16.csv%22&X-Amz-Signature=47af9a041970244b51fa6dd6a31d78ae9ff56a4db76a54d3e1b8a7ec4631defa",
"type" : "overview_v2",
"date_range" : {
"started_at" : "2018-03-13T00:00:00Z",
"ended_at" : "2018-06-13T00:00:00Z"
}
},
...
],
"pagination": {"cursor": "eyJiIjpudWxsLJxhIjoiIn0gf5"}
}
Get Bits Leaderboard
✎Gets a ranked list of Bits leaderboard information for an authorized broadcaster.
Authentication
- OAuth token required
- Required scope:
bits:read
URL
GET https://api.twitch.tv/helix/bits/leaderboard
Required Query Parameters
None
Optional Query Parameters
| Name | Type | Description |
|---|---|---|
count | integer | Number of results to be returned. Maximum: 100. Default: 10. |
period | string | Time period over which data is aggregated (PST time zone). This parameter interacts with started_at. Valid values follow. Default: "all".
|
started_at | string | Timestamp for the period over which the returned data is aggregated. Must be in RFC 3339 format. If this is not provided, data is aggregated over the current period; e.g., the current day/week/month/year. This value is ignored if period is "all".Any + operator should be URL encoded.Currently, the HH:MM:SS part of this value is used only to identify a given day in PST and otherwise ignored. For example, if the started_at value resolves to 5PM PST yesterday and period is "day", data is returned for all of yesterday. |
user_id | string | ID of the user whose results are returned; i.e., the person who paid for the Bits. As long as count is greater than 1, the returned data includes additional users, with Bits amounts above and below the user specified by user_id.If user_id is not provided, the endpoint returns the Bits leaderboard data across top users (subject to the value of count). |
Response Fields
| Field | Type | Description |
|---|---|---|
ended_at |
string | End of the date range for the returned data. |
rank |
integer | Leaderboard rank of the user. |
score |
integer | Leaderboard score (number of Bits) of the user. |
started_at |
string | Start of the date range for the returned data. |
total |
integer | Total number of results (users) returned. This is count or the total number of entries in the leaderboard, whichever is less. |
user_id |
string | ID of the user (viewer) in the leaderboard entry. |
user_login |
string | User login name. |
user_name |
string | Display name corresponding to user_id. |
Example Request
This gets information about the top two Bits leaderboard entries for the user specified by Bearer token cfabdegwdoklmawdzdo98xt2fo512y. Information is returned for the current week.
curl -X GET 'https://api.twitch.tv/helix/bits/leaderboard?count=2&period=week' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"user_id": "158010205",
"user_login": "tundracowboy",
"user_name": "TundraCowboy",
"rank": 1,
"score": 12543
},
{
"user_id": "7168163",
"user_login": "topramens",
"user_name": "Topramens",
"rank": 2,
"score": 6900
}
],
"date_range": {
"started_at": "2018-02-05T08:00:00Z",
"ended_at": "2018-02-12T08:00:00Z"
},
"total": 2
}
Get Cheermotes
✎Retrieves the list of available Cheermotes, animated emotes to which viewers can assign Bits, to cheer in chat. Cheermotes returned are available throughout Twitch, in all Bits-enabled channels.
URL
GET https://api.twitch.tv/helix/bits/cheermotes
Authentication
OAuth or App Access Token required.
Optional Query Parameter
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | ID for the broadcaster who might own specialized Cheermotes. |
Response Fields
| Parameter | Type | Description |
|---|---|---|
prefix |
string | The string used to Cheer that precedes the Bits amount. |
tiers |
array | An array of Cheermotes with their metadata. |
min_bits |
integer | Minimum number of bits needed to be used to hit the given tier of emote. |
id |
string | ID of the emote tier. Possible tiers are: 1,100,500,1000,5000, 10k, or 100k. |
color |
string | Hex code for the color associated with the bits of that tier. Grey, Purple, Teal, Blue, or Red color to match the base bit type. |
images |
object | Structure containing both animated and static image sets, sorted by light and dark. |
can_cheer |
Boolean | Indicates whether or not emote information is accessible to users. |
show_in_bits_card |
Boolean | Indicates whether or not we hide the emote from the bits card. |
type |
string | Shows whether the emote is global_first_party, global_third_party, channel_custom, display_only, or sponsored. |
order |
integer | Order of the emotes as shown in the bits card, in ascending order. |
last_updated |
string | The data when this Cheermote was last updated. |
is_charitable |
Boolean | Indicates whether or not this emote provides a charity contribution match during charity campaigns. |
Example Requests
This request lists all global Cheermotes.
curl -X GET 'https://api.twitch.tv/helix/bits/cheermotes' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
This request lists all global Cheermotes and any Cheermote uploaded by this broadcaster.
curl -X GET 'https://api.twitch.tv/helix/bits/cheermotes?broadcaster_id=41245072' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response
{
"data": [
{
"prefix": "Cheer",
"tiers": [
{
"min_bits": 1,
"id": "1",
"color": "#979797",
"images": {
"dark": {
"animated": {
"1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/1.gif",
"1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/1.5.gif",
"2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/2.gif",
"3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/3.gif",
"4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/4.gif"
},
"static": {
"1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/1.png",
"1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/1.5.png",
"2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/2.png",
"3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/3.png",
"4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/4.png"
}
},
"light": {
"animated": {
"1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/1.gif",
"1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/1.5.gif",
"2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/2.gif",
"3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/3.gif",
"4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/4.gif"
},
"static": {
"1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/1.png",
"1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/1.5.png",
"2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/2.png",
"3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/3.png",
"4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/4.png"
}
}
},
"can_cheer": true,
"show_in_bits_card": true
}
...
],
"type": "global_first_party",
"order": 1,
"last_updated": "2018-05-22T00:06:04Z",
"is_charitable": false
},
...
]
}
Get Extension Transactions
✎Get Extension Transactions allows extension back end servers to fetch a list of transactions that have occurred for their extension across all of Twitch. A transaction is a record of a user exchanging Bits for an in-Extension digital good.
URL
GET https://api.twitch.tv/helix/extensions/transactions
Description
Gets the list of Extension Transactions for a given extension.
Authentication
OAuth or App Access Token required.
Query Parameters
| Parameter | Required | Type | Description |
extension_id |
Yes | string | ID of the extension to list transactions for. Maximum: 1 |
id |
No | string | Transaction IDs to look up. Can include multiple to fetch multiple transactions in a single request. Format: Repeated Query Parameter, eg. /helix/extensions/transactions?extension_id=1234&id=1&id=2&id=3Maximum: 100 |
after |
No | string | The cursor used to fetch the next page of data. This only applies to queries without ID. If an ID is specified, it supersedes the cursor. |
first |
No | integer | Maximum number of objects to return. Maximum: 100 Default: 20 |
Return Values
| Parameter | Type | Description |
pagination |
object containing a string | If provided, is the key used to fetch the next page of data. If not provided, the current response is the last page of data available. |
data |
array | Array of requested transactions. |
id |
string | Unique identifier of the Bits in Extensions Transaction. |
timestamp |
string | UTC timestamp when this transaction occurred. |
broadcaster_id |
string | Twitch User ID of the channel the transaction occurred on. |
broadcaster_login |
string | Login name of the broadcaster. |
broadcaster_name |
string | Twitch Display Name of the broadcaster. |
user_id |
string | Twitch User ID of the user who generated the transaction. |
user_login |
string | Login name of the user who generated the transaction. |
user_name |
string | Twitch Display Name of the user who generated the transaction. |
product_type |
string | Enum of the product type. Currently only BITS_IN_EXTENSION. |
product_data |
object | JSON Object representing the product acquired, as it looked at the time of the transaction. |
domain |
string | Set this field to twitch.ext + your extension ID. |
broadcast |
Boolean | Flag that denotes whether or not the data was sent over the extension pubsub to all instances of the extension. |
expiration |
string | Always empty since only unexpired products can be purchased. |
sku |
string | Unique identifier for the product across the extension. |
cost |
object | JSON Object representing the cost to acquire the product. |
amount |
integer | Number of Bits required to acquire the product. |
| type` | enum | Always the string |
| “Bits”. | ||
displayName |
string | Display Name of the product. |
inDevelopment |
Boolean | Flag used to indicate if the product is in development. Either true or false. |
Example Request
curl -X GET
'https://api.twitch.tv/helix/extensions/transactions?extension_id=1234' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "74c52265-e214-48a6-91b9-23b6014e8041",
"timestamp": "2019-01-28T04:15:53.325Z",
"broadcaster_id": "439964613",
"broadcaster_login": "chikuseuma",
"broadcaster_name": "chikuseuma",
"user_id": "424596340",
"user_login": "quotrok",
"user_name": "quotrok",
"product_type": "BITS_IN_EXTENSION",
"product_data": {
"sku": "testSku100",
"cost": {
"amount": 100,
"type": "bits"
},
"displayName": "Test Sku",
"inDevelopment": false
}
},
{
"id": "8d303dc6-a460-4945-9f48-59c31d6735cb",
"timestamp": "2019-01-18T09:10:13.397Z",
"broadcaster_id": "439964613",
"broadcaster_login": "chikuseuma",
"broadcaster_name": "chikuseuma"
"user_id": "439966926",
"user_login": "liscuit",
"user_name": "liscuit",
"product_type": "BITS_IN_EXTENSION",
"product_data": {
"sku": "testSku100",
"cost": {
"amount": 100,
"type": "bits"
},
"displayName": "Test Sku",
"inDevelopment": false
}
},
...
],
"pagination": {
"cursor": "cursorString"
}
}
Get Channel Information
✎Gets channel information for users.
Authentication
Valid user token or app access token.
URL
GET https://api.twitch.tv/helix/channels
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | ID of the channel to be updated |
Optional Query Parameters
None
Return Values
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | Twitch User ID of this channel owner |
broadcaster_name |
string | Twitch user display name of this channel owner |
game_name |
string | Name of the game being played on the channel |
game_id |
string | Current game ID being played on the channel |
broadcaster_language |
string | Language of the channel. A language value is either the ISO 639-1 two-letter code for a supported stream language or “other”. |
title |
string | Title of the stream |
delay |
integer | Stream delay in seconds |
Response Codes
| HTTP Code | Meaning |
| 200 | Channel/Stream returned successfully |
| 400 | Missing Query Parameter |
| 500 | Internal Server Error; Failed to get channel information |
Example Request
This request gets information about the TwitchDev channel.
curl -X GET 'https://api.twitch.tv/helix/channels?broadcaster_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response
{
"data": [
{
"broadcaster_id": "141981764",
"broadcaster_login": "twitchdev",
"broadcaster_name": "TwitchDev",
"broadcaster_language": "en",
"game_id": "509670",
"game_name": "Science & Technology",
"title": "TwitchDev Monthly Update // May 6, 2021",
"delay": 0
}
]
}
Modify Channel Information
✎Modifies channel information for users.
Authentication
-
OAuth Token required
-
Required scope:
channel:manage:broadcast
URL
PATCH https://api.twitch.tv/helix/channels
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | ID of the channel to be updated |
Body Parameters
All parameters are optional, but at least one parameter must be provided.
| Parameter | Type | Description |
|---|---|---|
game_id |
string | The current game ID being played on the channel. Use “0” or “” (an empty string) to unset the game. |
broadcaster_language |
string | The language of the channel. A language value must be either the ISO 639-1 two-letter code for a supported stream language or “other”. |
title |
string | The title of the stream. Value must not be an empty string. |
delay |
integer | Stream delay in seconds. Stream delay is a Twitch Partner feature; trying to set this value for other account types will return a 400 error. |
Response Codes
| HTTP Code | Meaning |
|---|---|
| 204 | Channel/Stream updated successfully |
| 400 | Missing or invalid parameter |
| 500 | Internal server error; failed to update channel |
Example Request
curl -X PATCH 'https://api.twitch.tv/helix/channels?broadcaster_id=41245072' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
--data-raw '{"game_id":"33214", "title":"there are helicopters in the game? REASON TO PLAY FORTNITE found", "broadcaster_language":"en"}'
Example Response
204 No Content
Get Channel Editors
✎Gets a list of users who have editor permissions for a specific channel.
Authentication
- OAuth user token required
- Required scope:
channel:read:editors
URL
GET https://api.twitch.tv/helix/channels/editors
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | Broadcaster’s user ID associated with the channel. |
Optional Query Parameters
None.
Response Fields
| Field | Type | Description |
|---|---|---|
user_id |
string | User ID of the editor. |
user_name |
string | Display name of the editor. |
created_at |
string | Date and time the editor was given editor permissions. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | A list of channel editors is returned. |
| 400 | Query parameter is missing. |
| 401 | Authorization is missing or there was an OAuth token mismatch. |
Example Request
This example gets a list of editors for the TwitchDev channel which has a User ID of 141981764.
curl -X GET 'https://api.twitch.tv/helix/channels/editors?broadcaster_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
Example Response
{
"data": [
{
"user_id": "182891647",
"user_name": "mauerbac",
"created_at": "2019-02-15T21:19:50.380833Z"
},
{
"user_id": "135093069",
"user_name": "BlueLava",
"created_at": "2018-03-07T16:28:29.872937Z"
}
]
}
Create Custom Rewards
✎Creates a Custom Reward on a channel.
Authentication
- User OAuth token
- Required scope:
channel:manage:redemptions
URL
POST https://api.twitch.tv/helix/channel_points/custom_rewards
Pagination
None.
Required Query Parameter
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | Provided broadcaster_id must match the user_id in the user OAuth token. |
Required Body Parameters
| Parameter | Type | Description |
|---|---|---|
title |
string | The title of the reward. |
cost |
integer | The cost of the reward. |
Optional Body Parameters
| Parameter | Type | Description |
|---|---|---|
prompt |
string | The prompt for the viewer when redeeming the reward. |
is_enabled |
boolean | Is the reward currently enabled, if false the reward won’t show up to viewers. Default: true |
background_color |
string | Custom background color for the reward. Format: Hex with # prefix. Example: #00E5CB. |
is_user_input_required |
boolean | Does the user need to enter information when redeeming the reward. Default: false. |
is_max_per_stream_enabled |
boolean | Whether a maximum per stream is enabled. Default: false. |
max_per_stream |
integer | The maximum number per stream if enabled. Required when any value of is_max_per_stream_enabled is included. |
is_max_per_user_per_stream_enabled |
boolean | Whether a maximum per user per stream is enabled. Default: false. |
max_per_user_per_stream |
integer | The maximum number per user per stream if enabled. Required when any value of is_max_per_user_per_stream_enabled is included. |
is_global_cooldown_enabled |
boolean | Whether a cooldown is enabled. Default: false. |
global_cooldown_seconds |
integer | The cooldown in seconds if enabled. Required when any value of is_global_cooldown_enabled is included. |
should_redemptions_skip_request_queue |
boolean | Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status. Default: false. |
Return Values
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | ID of the channel the reward is for. |
broadcaster_login |
string | Broadcaster’s user login name. |
broadcaster_name |
string | Display name of the channel the reward is for. |
id |
string | ID of the reward. |
title |
string | The title of the reward. |
prompt |
string | The prompt for the viewer when they are redeeming the reward. |
cost |
integer | The cost of the reward. |
image |
object | Set of custom images of 1x, 2x and 4x sizes for the reward { url_1x: string, url_2x: string, url_4x: string }, can be null if no images have been uploaded |
default_image |
object | Set of default images of 1x, 2x and 4x sizes for the reward { url_1x: string, url_2x: string, url_4x: string } |
background_color |
string | Custom background color for the reward. Format: Hex with # prefix. Example: #00E5CB. |
is_enabled |
boolean | Is the reward currently enabled, if false the reward won’t show up to viewers |
is_user_input_required |
boolean | Does the user need to enter information when redeeming the reward |
max_per_stream_setting |
object | Whether a maximum per stream is enabled and what the maximum is. { is_enabled: bool, max_per_stream: int } |
max_per_user_per_stream_setting |
object | Whether a maximum per user per stream is enabled and what the maximum is. { is_enabled: bool, max_per_user_per_stream: int } |
global_cooldown_setting |
object | Whether a cooldown is enabled and what the cooldown is. { is_enabled: bool, global_cooldown_seconds: int } |
is_paused |
boolean | Is the reward currently paused, if true viewers can’t redeem |
is_in_stock |
boolean | Is the reward currently in stock, if false viewers can’t redeem |
should_redemptions_skip_request_queue |
boolean | Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status. |
redemptions_redeemed_current_stream |
integer | The number of redemptions redeemed during the current live stream. Counts against the max_per_stream_setting limit. Null if the broadcasters stream isn’t live or max_per_stream_setting isn’t enabled. |
cooldown_expires_at |
string | Timestamp of the cooldown expiration. Null if the reward isn’t on cooldown. |
Response Codes
| HTTP Code | Meaning |
|---|---|
| 200 | OK: A list of the Custom Rewards is returned |
| 400 | Bad Request: Query Parameter missing or invalid |
| 401 | Unauthenticated: Missing/invalid Token |
| 403 | Forbidden: Channel Points are not available for the broadcaster |
| 500 | Internal Server Error: Something bad happened on our side |
Example Request
This request creates a custom reward:
curl -X POST 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
"title":"game analysis 1v1",
"cost":50000
}'
Example Response
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "afaa7e34-6b17-49f0-a19a-d1e76eaaf673",
"image": null,
"background_color": "#00E5CB",
"is_enabled": true,
"cost": 50000,
"title": "game analysis 1v1",
"prompt": "",
"is_user_input_required": false,
"max_per_stream_setting": {
"is_enabled": false,
"max_per_stream": 0
},
"max_per_user_per_stream_setting": {
"is_enabled": false,
"max_per_user_per_stream": 0
},
"global_cooldown_setting": {
"is_enabled": false,
"global_cooldown_seconds": 0
},
"is_paused": false,
"is_in_stock": true,
"default_image": {
"url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
"url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
"url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
},
"should_redemptions_skip_request_queue": false,
"redemptions_redeemed_current_stream": null,
"cooldown_expires_at": null
}
]
}
Delete Custom Reward
✎Deletes a Custom Reward on a channel.
The Custom Reward specified by id must have been created by the client_id attached to the OAuth token in order to be deleted. Any UNFULFILLED Custom Reward Redemptions of the deleted Custom Reward will be updated to the FULFILLED status.
Authentication
- User OAuth token
- Required scope:
channel:manage:redemptions
URL
DELETE https://api.twitch.tv/helix/channel_points/custom_rewards
Pagination
None.
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | Provided broadcaster_id must match the user_id in the user OAuth token. |
id |
string | ID of the Custom Reward to delete, must match a Custom Reward on broadcaster_id’s channel. |
Response Codes
| HTTP Code | Meaning |
|---|---|
| 204 | No Content. |
| 400 | Bad Request: Query/Body Parameter missing or invalid. |
| 401 | Unauthenticated: Missing/invalid Token. |
| 403 | Forbidden: The Custom Reward was created by a different client_id or Channel Points are not available for the broadcaster |
| 404 | Not Found: The Custom Reward doesn’t exist with the id and broadcaster_id specified |
| 500 | Internal Server Error: Something bad happened on our side |
Example Request
This request deletes a custom reward:
curl -X DELETE 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=b045196d-9ce7-4a27-a9b9-279ed341ab28' \
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'
Example Response
204 No Content
Get Custom Reward
✎Returns a list of Custom Reward objects for the Custom Rewards on a channel.
Authentication
- User OAuth token
- Required scope:
channel:read:redemptions
URL
GET https://api.twitch.tv/helix/channel_points/custom_rewards
Pagination
None.
There is a limit of 50 Custom Rewards on a channel at a time. This includes both enabled and disabled Custom Rewards.
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | Provided broadcaster_id must match the user_id in the user OAuth token. |
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
id |
string | When used, this parameter filters the results and only returns reward objects for the Custom Rewards with matching ID. Maximum: 50 |
only_manageable_rewards |
Boolean | When set to true, only returns custom rewards that the calling client_id can manage. Default: false. |
Return Values
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | ID of the channel the reward is for. |
broadcaster_login |
string | Login of the channel the reward is for. |
broadcaster_name |
string | Display name of the channel the reward is for. |
id |
string | ID of the reward. |
title |
string | The title of the reward. |
prompt |
string | The prompt for the viewer when redeeming the reward. |
cost |
integer | The cost of the reward. |
image |
object | Set of custom images of 1x, 2x and 4x sizes for the reward { url_1x: string, url_2x: string, url_4x: string }, can be null if no images have been uploaded. |
default_image |
object | Set of default images of 1x, 2x and 4x sizes for the reward { url_1x: string, url_2x: string, url_4x: string } |
background_color |
string | Custom background color for the reward. Format: Hex with # prefix. Example: #00E5CB. |
is_enabled |
boolean | Is the reward currently enabled, if false the reward won’t show up to viewers. |
is_user_input_required |
boolean | Does the user need to enter information when redeeming the reward |
max_per_stream_setting |
object | Whether a maximum per stream is enabled and what the maximum is. { is_enabled: bool, max_per_stream: int } |
max_per_user_per_stream_setting |
object | Whether a maximum per user per stream is enabled and what the maximum is. { is_enabled: bool, max_per_user_per_stream: int } |
global_cooldown_setting |
object | Whether a cooldown is enabled and what the cooldown is. { is_enabled: bool, global_cooldown_seconds: int } |
is_paused |
boolean | Is the reward currently paused, if true viewers can’t redeem. |
is_in_stock |
boolean | Is the reward currently in stock, if false viewers can’t redeem. |
should_redemptions_skip_request_queue |
boolean | Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status. |
redemptions_redeemed_current_stream |
integer | The number of redemptions redeemed during the current live stream. Counts against the max_per_stream_setting limit. Null if the broadcasters stream isn’t live or max_per_stream_setting isn’t enabled. |
cooldown_expires_at |
string | Timestamp of the cooldown expiration. Null if the reward isn’t on cooldown. |
Response Codes
| HTTP Code | Meaning |
|---|---|
| 200 | OK: A list of the Custom Rewards is returned |
| 400 | Bad Request: Query Parameter missing or invalid |
| 401 | Unauthenticated: Missing/invalid Token |
| 403 | Forbidden: Channel Points are not available for the broadcaster |
| 404 | Not Found: No Custom Rewards with the specified IDs were found |
| 500 | Internal Server Error: Something bad happened on our side |
Example Request #1
This request lists custom rewards:
curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212'
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'
Example Response #1
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"image": null,
"background_color": "#00E5CB",
"is_enabled": true,
"cost": 50000,
"title": "game analysis",
"prompt": "",
"is_user_input_required": false,
"max_per_stream_setting": {
"is_enabled": false,
"max_per_stream": 0
},
"max_per_user_per_stream_setting": {
"is_enabled": false,
"max_per_user_per_stream": 0
},
"global_cooldown_setting": {
"is_enabled": false,
"global_cooldown_seconds": 0
},
"is_paused": false,
"is_in_stock": true,
"default_image": {
"url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
"url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
"url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
},
"should_redemptions_skip_request_queue": false,
"redemptions_redeemed_current_stream": null,
"cooldown_expires_at": null
}
]
}
Example Request #2
This request lists custom rewards that the calling Client ID can manage:
curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&only_manageable_rewards=true'
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'
Example Response #2
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_id": "274637212",
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"image": null,
"background_color": "#00E5CB",
"is_enabled": true,
"cost": 50000,
"title": "game analysis",
"prompt": "",
"is_user_input_required": false,
"max_per_stream_setting": {
"is_enabled": false,
"max_per_stream": 0
},
"max_per_user_per_stream_setting": {
"is_enabled": false,
"max_per_user_per_stream": 0
},
"global_cooldown_setting": {
"is_enabled": false,
"global_cooldown_seconds": 0
},
"is_paused": false,
"is_in_stock": true,
"default_image": {
"url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
"url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
"url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
},
"should_redemptions_skip_request_queue": false,
"redemptions_redeemed_current_stream": null,
"cooldown_expires_at": null
}
]
}
Example Request #3
This request bulk-gets custom rewards.
curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01'
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'
Example Response #3
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_id": "274637212",
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"image": null,
"background_color": "#00E5CB",
"is_enabled": true,
"cost": 50000,
"title": "game analysis",
"prompt": "",
"is_user_input_required": false,
"max_per_stream_setting": {
"is_enabled": false,
"max_per_stream": 0
},
"max_per_user_per_stream_setting": {
"is_enabled": false,
"max_per_user_per_stream": 0
},
"global_cooldown_setting": {
"is_enabled": false,
"global_cooldown_seconds": 0
},
"is_paused": false,
"is_in_stock": true,
"default_image": {
"url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
"url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
"url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
},
"should_redemptions_skip_request_queue": false,
"redemptions_redeemed_current_stream": null,
"cooldown_expires_at": null
}
]
}
Get Custom Reward Redemption
✎Returns Custom Reward Redemption objects for a Custom Reward on a channel that was created by the same client_id.
Developers only have access to get and update redemptions for the rewards created programmatically by the same client_id.
Authentication
- User OAuth token
- Required scope:
channel:read:redemptions
URL
GET https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions
Pagination
Maximum of 50 per page. Returns oldest first.
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | Provided broadcaster_id must match the user_id in the user OAuth token. |
reward_id |
string | When ID is not provided, this parameter returns paginated Custom Reward Redemption objects for redemptions of the Custom Reward with ID reward_id. |
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
id |
string | When used, this param filters the results and only returns Custom Reward Redemption objects for the redemptions with matching ID. Maximum: 50 |
status |
string | When id is not provided, this param is required and filters the paginated Custom Reward Redemption objects for redemptions with the matching status. Can be one of UNFULFILLED, FULFILLED or CANCELED |
sort |
string | Sort order of redemptions returned when getting the paginated Custom Reward Redemption objects for a reward. One of: OLDEST, NEWEST. Default: OLDEST. |
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries without ID. If an ID is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query. |
first |
integer | Number of results to be returned when getting the paginated Custom Reward Redemption objects for a reward. Limit: 50. Default: 20. |
Return Values
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | The id of the broadcaster that the reward belongs to. |
broadcaster_login |
string | Broadcaster’s user login name. |
broadcaster_name |
string | The display name of the broadcaster that the reward belongs to. |
id |
string | The ID of the redemption. |
user_login |
string | The login of the user who redeemed the reward. |
user_id |
string | The ID of the user that redeemed the reward. |
user_name |
string | The display name of the user that redeemed the reward. |
reward |
object | Basic information about the Custom Reward that was redeemed at the time it was redeemed. { “id”: string, “title”: string, “prompt”: string, “cost”: int, } |
user_input |
string | The user input provided. Empty string if not provided. |
status |
string | One of UNFULFILLED, FULFILLED or CANCELED |
redeemed_at |
string | RFC3339 timestamp of when the reward was redeemed. |
Response Codes
| HTTP Code | Meaning |
|---|---|
| 200 | Ok: A list of the Custom Reward Redemptions is returned |
| 400 | Bad Request: Query Parameter missing or invalid |
| 401 | Unauthenticated: Missing/invalid Token |
| 403 | Forbidden: The Custom Reward was created by a different client_id or Channel Points are not available for the broadcaster |
| 404 | Not Found: No Custom Reward Redemptions with the specified ids were found |
| 500 | Internal Server Error: Something bad happened on our side |
Example Request #1
This example lists custom reward redemptions for a specific reward:
curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=274637212&reward_id=92af127c-7326-4483-a52b-b0da0be61c01&status=CANCELED' \
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'
Example Response #1
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "17fa2df1-ad76-4804-bfa5-a40ef63efe63",
"user_login": "torpedo09",
"user_id": "274637212",
"user_name": "torpedo09",
"user_input": "",
"status": "CANCELED",
"redeemed_at": "2020-07-01T18:37:32Z",
"reward": {
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"title": "game analysis",
"prompt": "",
"cost": 50000
}
}
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6Ik1UZG1ZVEprWmpFdFlXUTNOaTAwT0RBMExXSm1ZVFV0WVRRd1pXWTJNMlZtWlRZelgxOHlNREl3TFRBM0xUQXhWREU0T2pNM09qTXlMakl6TXpFeU56RTFOMW89In19"
}
}
Example Request #2
This example gets custom reward redemptions by ID.
curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=274637212&reward_id=92af127c-7326-4483-a52b-b0da0be61c01&id=17fa2df1-ad76-4804-bfa5-a40ef63efe63' \
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'
Example Response #2
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "17fa2df1-ad76-4804-bfa5-a40ef63efe63",
"user_id": "274637212",
"user_name": "torpedo09",
"user_input": "",
"status": "CANCELED",
"redeemed_at": "2020-07-01T18:37:32Z",
"reward": {
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"title": "game analysis",
"prompt": "",
"cost": 50000
}
}
]
}
Update Custom Reward
✎Updates a Custom Reward created on a channel.
The Custom Reward specified by id must have been created by the client_id attached to the user OAuth token.
Authentication
- User OAuth token
- Required scope:
channel:manage:redemptions
URL
PATCH https://api.twitch.tv/helix/channel_points/custom_rewards
Pagination
None.
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | Provided broadcaster_id must match the user_id in the user OAuth token. |
id |
string | ID of the Custom Reward to update. Must match a Custom Reward on the channel of the broadcaster_id. |
Optional Body Values
| Parameter | Type | Description |
|---|---|---|
title |
string | The title of the reward. |
prompt |
string | The prompt for the viewer when they are redeeming the reward. |
cost |
integer | The cost of the reward. |
background_color |
string | Custom background color for the reward as a hexadecimal value. Example: #00E5CB. |
is_enabled |
boolean | Is the reward currently enabled, if false the reward won’t show up to viewers. |
is_user_input_required |
boolean | Does the user need to enter information when redeeming the reward. |
is_max_per_stream_enabled |
boolean | Whether a maximum per stream is enabled. Required when any value of max_per_stream is included. |
max_per_stream |
integer | The maximum number per stream if enabled. Required when any value of is_max_per_stream_enabled is included. |
is_max_per_user_per_stream_enabled |
boolean | Whether a maximum per user per stream is enabled. Required when any value of max_per_user_per_stream is included. |
max_per_user_per_stream |
integer | The maximum number per user per stream if enabled. Required when any value of is_max_per_user_per_stream_enabled is included. |
is_global_cooldown_enabled |
boolean | Whether a cooldown is enabled. Required when any value of global_cooldown_seconds is included. |
global_cooldown_seconds |
integer | The cooldown in seconds if enabled. Required when any value of is_global_cooldown_enabled is included. |
is_paused |
boolean | Is the reward currently paused, if true viewers cannot redeem. |
should_redemptions_skip_request_queue |
boolean | Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status. |
Return Values
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | ID of the channel the reward is for. |
broadcaster_login |
string | Broadcaster’s user login name. |
broadcaster_name |
string | Display name of the channel the reward is for. |
id |
string | ID of the reward. |
title |
string | The title of the reward. |
prompt |
string | The prompt for the viewer when they are redeeming the reward. |
cost |
integer | The cost of the reward. |
image |
object | Set of custom images of 1x, 2x, and 4x sizes for the reward, can be null if no images have been uploaded. |
default_image |
object | Set of default images of 1x, 2x, and 4x sizes for the reward. |
background_color |
string | Custom background color for the reward as a hexadecimal value. Example: #00E5CB. |
is_enabled |
boolean | Is the reward currently enabled, if false the reward won’t show up to viewers. |
is_user_input_required |
boolean | Does the user need to enter information when redeeming the reward. |
max_per_stream_setting |
object | Whether a maximum per stream is enabled and what the maximum is. |
max_per_user_per_stream_setting |
object | Whether a maximum per user per stream is enabled and what the maximum is. |
global_cooldown_setting |
object | Whether a cooldown is enabled and what the cooldown is. |
is_paused |
boolean | Is the reward currently paused, if true viewers cannot redeem. |
is_in_stock |
boolean | Is the reward currently in stock, if false viewers can’t redeem. |
should_redemptions_skip_request_queue |
boolean | Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status. |
redemptions_redeemed_current_stream |
integer | The number of redemptions redeemed during the current live stream. Counts against the max_per_stream_setting limit. null if the broadcasters stream is not live or max_per_stream_setting is not enabled. |
cooldown_expires_at |
string | Timestamp of the cooldown expiration. null if the reward is not on cooldown. |
Response Codes
| HTTP Code | Meaning |
|---|---|
| 200 | OK: A list of the Custom Rewards is returned. |
| 400 | Bad Request: Query Parameter missing or invalid. This includes the required parameter pairs to set max per stream, max per user per stream, and global cooldown. |
| 401 | Unauthenticated: Missing/invalid Token. |
| 403 | Forbidden: The Custom Reward was created by a different client_id or Channel Points are not available for the broadcaster. |
| 404 | Not Found: The Custom Reward does not exist with the id and broadcaster_id specified. |
| 500 | Internal Server Error: Could not update the Custom Reward. |
Example Request #1
This request disables a custom reward:
curl -X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
"is_enabled": false
}'
Example Response #1
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"image": null,
"background_color": "#00E5CB",
"is_enabled": false,
"cost": 30000,
"title": "game analysis 2v2",
"prompt": "",
"is_user_input_required": false,
"max_per_stream_setting": {
"is_enabled": true,
"max_per_stream": 60
},
"max_per_user_per_stream_setting": {
"is_enabled": false,
"max_per_user_per_stream": 0
},
"global_cooldown_setting": {
"is_enabled": false,
"global_cooldown_seconds": 0
},
"is_paused": false,
"is_in_stock": false,
"default_image": {
"url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
"url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
"url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
},
"should_redemptions_skip_request_queue": true,
"redemptions_redeemed_current_stream": 60,
"cooldown_expires_at": null
}
]
}
Example Request #2
curl -X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
"title": "game analysis 2v2"
}'
Example Response #2
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"image": null,
"background_color": "",
"is_enabled": false,
"cost": 30000,
"title": "game analysis 2v2",
"prompt": "",
"is_user_input_required": false,
"max_per_stream_setting": {
"is_enabled": true,
"max_per_stream": 60
},
"max_per_user_per_stream_setting": {
"is_enabled": false,
"max_per_user_per_stream": 0
},
"global_cooldown_setting": {
"is_enabled": false,
"global_cooldown_seconds": 0
},
"is_paused": false,
"is_in_stock": true,
"default_image": {
"url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
"url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
"url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
},
"should_redemptions_skip_request_queue": true,
"redemptions_redeemed_current_stream": 60,
"cooldown_expires_at": null
}
]
}
Update Redemption Status
✎Updates the status of Custom Reward Redemption objects on a channel that are in the UNFULFILLED status.
The Custom Reward Redemption specified by id must be for a Custom Reward created by the client_id attached to the user OAuth token.
Authentication
- User OAuth token
- Required scope:
channel:manage:redemptions
URL
PATCH https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions
Pagination
None.
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
id |
string | ID of the Custom Reward Redemption to update, must match a Custom Reward Redemption on broadcaster_id’s channel. Maximum: 50. |
broadcaster_id |
string | Provided broadcaster_id must match the user_id in the user OAuth token. |
reward_id |
string | ID of the Custom Reward the redemptions to be updated are for. |
Required Body Values
| Parameter | Type | Description |
|---|---|---|
status |
string | The new status to set redemptions to. Can be either FULFILLED or CANCELED. Updating to CANCELED will refund the user their Channel Points. |
Return Values
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | The ID of the broadcaster that the reward belongs to. |
broadcaster_login |
string | Broadcaster’s user login name. |
broadcaster_name |
string | The display name of the broadcaster that the reward belongs to. |
id |
string | The ID of the redemption. |
user_id |
string | The ID of the user that redeemed the reward. |
user_name |
string | The display name of the user that redeemed the reward. |
user_login |
string | The login of the user that redeemed the reward. |
reward |
object | Basic information about the Custom Reward that was redeemed at the time it was redeemed. { “id”: string, “title”: string, “prompt”: string, “cost”: int, } |
user_input |
string | The user input provided. Null if not provided. |
status |
string | One of UNFULFILLED, FULFILLED or CANCELED. |
redeemed_at |
string | RFC3339 timestamp of when the reward was redeemed. |
Response Codes
| HTTP Code | Meaning |
|---|---|
| 200 | OK: A list of the updated Custom Reward Redemptions is returned |
| 400 | Bad Request: Query Parameter missing or invalid |
| 401 | Unauthenticated: Missing/invalid Token |
| 403 | Forbidden: The Custom Reward was created by a different client_id or Channel Points are not available for the broadcaster |
| 404 | Not Found: No Custom Reward Redemptions with the specified IDs were found with a status of UNFULFILLED. |
| 500 | Internal Server Error: Something bad happened on our side |
Example Request
This request updates custom reward redemption status.
curl --X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=274637212&reward_id=92af127c-7326-4483-a52b-b0da0be61c01&id=17fa2df1-ad76-4804-bfa5-a40ef63efe63' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
"status":"CANCELED"
}'
Example Response
{
"data": [
{
"broadcaster_name": "torpedo09",
"broadcaster_login": "torpedo09",
"broadcaster_id": "274637212",
"id": "17fa2df1-ad76-4804-bfa5-a40ef63efe63",
"user_id": "274637212",
"user_name": "torpedo09",
"user_login": "torpedo09",
"user_input": "",
"status": "CANCELED",
"redeemed_at": "2020-07-01T18:37:32Z",
"reward": {
"id": "92af127c-7326-4483-a52b-b0da0be61c01",
"title": "game analysis",
"prompt": "",
"cost": 50000
}
}
]
}
Get Channel Emotes
✎NEW Gets all custom emotes for a specific Twitch channel including subscriber emotes, Bits tier emotes, and follower emotes. Custom channel emotes are custom emoticons that viewers may use in Twitch chat once they are subscribed to, cheered in, or followed the channel that owns the emotes.
Authorization
- User OAuth Token or App Access Token
URL
GET https://api.twitch.tv/helix/chat/emotes
Pagination Support
None.
Required Query Parameter
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | The broadcaster whose emotes are being requested. Maximum: 1 |
Return Values
| Parameter | Type | Description |
|---|---|---|
id |
string | ID of the emote. |
name |
string | Name of the emote a viewer types into Twitch chat for the image to appear. |
images |
object | Object of image URLs for the emote. |
images.url_1x |
string | Small emote image URL. |
images.url_2x |
string | Medium emote image URL. |
images.url_4x |
string | Large emote image URL. |
tier |
string | If the emote_type is "subscriptions", this indicates the subscriber tier at which the emote is unlocked. Set to an empty string otherwise. |
emote_type |
string | The type of emote. The most common values for custom channel emotes are:subscriptions: Indicates a custom subscriber emote.bitstier: Indicates a custom Bits tier emote.follower: Indicates a custom follower emote. |
emote_set_id |
string | ID of the emote set the emote belongs to. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Custom channel emotes returned successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Returns custom emotes for the TwitchDev channel.
curl -X GET 'https://api.twitch.tv/helix/chat/emotes?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "304456832",
"name": "twitchdevPitchfork",
"images": {
"url_1x": "https://static-cdn.jtvnw.net/emoticons/v1/304456832/1.0",
"url_2x": "https://static-cdn.jtvnw.net/emoticons/v1/304456832/2.0",
"url_4x": "https://static-cdn.jtvnw.net/emoticons/v1/304456832/3.0"
},
"tier": "1000",
"emote_type": "subscriptions",
"emote_set_id": "301590448"
},
...
]
}
Get Global Emotes
✎NEW Gets all global emotes. Global emotes are Twitch-specific emoticons that every user can use in Twitch chat.
Authorization
- User OAuth Token or App Access Token
URL
GET https://api.twitch.tv/helix/chat/emotes/global
Pagination Support
None.
Return Values
| Parameter | Type | Description |
|---|---|---|
id |
string | ID of the emote. |
name |
string | Name of the emote a viewer types into Twitch chat for the image to appear. |
images |
object | Object of image URLs for the emote. |
images.url_1x |
string | Small emote image URL. |
images.url_2x |
string | Medium emote image URL. |
images.url_4x |
string | Large emote image URL. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Global emotes returned successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Returns all global emotes.
curl -X GET 'https://api.twitch.tv/helix/chat/emotes/global' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
...
{
"id": "196892",
"name": "TwitchUnity",
"images": {
"url_1x": "https://static-cdn.jtvnw.net/emoticons/v1/196892/1.0",
"url_2x": "https://static-cdn.jtvnw.net/emoticons/v1/196892/2.0",
"url_4x": "https://static-cdn.jtvnw.net/emoticons/v1/196892/3.0"
}
},
...
]
}
Get Emote Sets
✎NEW Gets all Twitch emotes for one or more specific emote sets.
Authorization
- User OAuth Token or App Access Token
URL
GET https://api.twitch.tv/helix/chat/emotes/set
Pagination Support
None.
Required Query Parameter
| Parameter | Type | Description |
|---|---|---|
emote_set_id |
string | ID(s) of the emote set. Minimum: 1. Maximum: 25. |
Return Values
| Parameter | Type | Description |
|---|---|---|
id |
string | Emote ID. |
name |
string | Name of the emote a viewer types into Twitch chat for the image to appear. |
images |
object | Object of image URLs for the emote. |
images.url_1x |
string | Small emote image URL. |
images.url_2x |
string | Medium emote image URL. |
images.url_4x |
string | Large emote image URL. |
emote_type |
string | The type of emote. |
emote_set_id |
string | ID of the emote set the emote belongs to. |
owner_id |
string | User ID of the broadcaster who owns the emote. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Emotes for specific emote sets returned successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Returns the emotes for the TwitchDev subscriber emote set.
curl -X GET 'https://api.twitch.tv/helix/chat/emotes/set?emote_set_id=301590448' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "304456832",
"name": "twitchdevPitchfork",
"images": {
"url_1x": "https://static-cdn.jtvnw.net/emoticons/v1/304456832/1.0",
"url_2x": "https://static-cdn.jtvnw.net/emoticons/v1/304456832/2.0",
"url_4x": "https://static-cdn.jtvnw.net/emoticons/v1/304456832/3.0"
},
"emote_type": "subscriptions",
"emote_set_id": "301590448",
"owner_id": "141981764"
},
...
]
}
Get Channel Chat Badges
✎NEW Gets a list of custom chat badges that can be used in chat for the specified channel. This includes subscriber badges and Bit badges.
Authorization
- User OAuth Token
URL
GET https://api.twitch.tv/helix/chat/badges
Pagination Support
None.
Required Query Parameter
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | The broadcaster whose chat badges are being requested. Provided broadcaster_id must match the user_id in the user OAuth token.Maximum: 1 |
Return Values
| Parameter | Type | Description |
|---|---|---|
data |
Array of objects | An array of chat badge sets. |
set.set_id |
string | ID for the chat badge set. |
set.versions |
Array of objects | Contains chat badge objects for the set. |
set.version.id |
string | ID of the chat badge version. |
set.version.image_url_1x |
string | Small image URL. |
set.version.image_url_2x |
string | Medium image URL. |
set.version.image_url_4x |
string | Large image URL. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Channel chat badges returned successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Returns custom chat badges for the BlueLava Twitch channel.
curl -X GET 'https://api.twitch.tv/helix/chat/badges?broadcaster_id=135093069' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"set_id": "bits",
"versions": [
{
"id": "1",
"image_url_1x": "https://static-cdn.jtvnw.net/badges/v1/743a0f3b-84b3-450b-96a0-503d7f4a9764/1",
"image_url_2x": "https://static-cdn.jtvnw.net/badges/v1/743a0f3b-84b3-450b-96a0-503d7f4a9764/2",
"image_url_4x": "https://static-cdn.jtvnw.net/badges/v1/743a0f3b-84b3-450b-96a0-503d7f4a9764/3"
}
]
},
{
"set_id": "subscriber",
"versions": [
{
"id": "0",
"image_url_1x": "https://static-cdn.jtvnw.net/badges/v1/eb4a8a4c-eacd-4f5e-b9f2-394348310442/1",
"image_url_2x": "https://static-cdn.jtvnw.net/badges/v1/eb4a8a4c-eacd-4f5e-b9f2-394348310442/2",
"image_url_4x": "https://static-cdn.jtvnw.net/badges/v1/eb4a8a4c-eacd-4f5e-b9f2-394348310442/3"
},
...
]
}
]
}
Get Global Chat Badges
✎NEW Gets a list of chat badges that can be used in chat for any channel.
Authorization
- User OAuth Token or App Access Token
URL
GET https://api.twitch.tv/helix/chat/badges/global
Pagination Support
None.
Return Values
| Parameter | Type | Description |
|---|---|---|
data |
Array of objects | An array of chat badge sets. |
set.set_id |
string | ID for the chat badge set. |
set.versions |
Array of objects | Contains chat badge objects for the set. |
set.version.id |
string | ID of the chat badge version. |
set.version.image_url_1x |
string | Small image URL. |
set.version.image_url_2x |
string | Medium image URL. |
set.version.image_url_4x |
string | Large image URL. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Global chat badges returned successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Returns global chat badges.
curl -X GET 'https://api.twitch.tv/helix/chat/badges/global' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
...
{
"set_id": "vip",
"versions": [
{
"id": "1",
"image_url_1x": "https://static-cdn.jtvnw.net/badges/v1/b817aba4-fad8-49e2-b88a-7cc744dfa6ec/1",
"image_url_2x": "https://static-cdn.jtvnw.net/badges/v1/b817aba4-fad8-49e2-b88a-7cc744dfa6ec/2",
"image_url_4x": "https://static-cdn.jtvnw.net/badges/v1/b817aba4-fad8-49e2-b88a-7cc744dfa6ec/3"
}
]
},
...
]
}
Create Clip
✎Creates a clip programmatically. This returns both an ID and an edit URL for the new clip.
Note: The clips service returns a maximum of 1000 clips,
Clip creation takes time. We recommend that you query Get Clips, with the clip ID that is returned here. If Get Clips returns a valid clip, your clip creation was successful. If, after 15 seconds, you still have not gotten back a valid clip from Get Clips, assume that the clip was not created and retry Create Clip.
This endpoint has a global rate limit, across all callers. The limit may change over time, but the response includes informative headers:
Ratelimit-Helixclipscreation-Limit: <int value>
Ratelimit-Helixclipscreation-Remaining: <int value>
Authentication
- OAuth token required
- Required scope:
clips:edit
URL
POST https://api.twitch.tv/helix/clips
Required Query Parameter
| Name | Type | Description |
|---|---|---|
broadcaster_id |
string | ID of the stream from which the clip will be made. |
Optional Query Parameter
| Name | Type | Description |
|---|---|---|
has_delay |
boolean | If false, the clip is captured from the live stream when the API is called; otherwise, a delay is added before the clip is captured (to account for the brief delay between the broadcaster’s stream and the viewer’s experience of that stream). Default: false. |
Response Fields
| Field | Type | Description |
|---|---|---|
edit_url |
string | URL of the edit page for the clip. |
id |
string | ID of the clip that was created. |
Example Request
curl -X POST 'https://api.twitch.tv/helix/clips?broadcaster_id=44322889' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data":
[{
"id": "FiveWordsForClipSlug",
"edit_url": "http://clips.twitch.tv/FiveWordsForClipSlug/edit"
}]
}
Get Clips
✎Gets clip information by clip ID (one or more), broadcaster ID (one only), or game ID (one only).
Note: The clips service returns a maximum of 1000 clips.
The response has a JSON payload with a data field containing an array of clip information elements and a pagination field containing information required to query for more streams.
Authentication
OAuth or App Access Token required.
URL
GET https://api.twitch.tv/helix/clips
Required Query Parameter
| Name | Type | Description |
|---|---|---|
broadcaster_id |
string | ID of the broadcaster for whom clips are returned. The number of clips returned is determined by the first query-string parameter (default: 20). Results are ordered by view count. |
game_id |
string | ID of the game for which clips are returned. The number of clips returned is determined by the first query-string parameter (default: 20). Results are ordered by view count. |
id |
string | ID of the clip being queried. Limit: 100. |
For a query to be valid, id (one or more), broadcaster_id, or game_id must be specified. You may specify only one of these parameters.
Optional Query Parameters
| Name | Type | Description |
|---|---|---|
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries specifying broadcaster_id or game_id. The cursor value specified here is from the pagination response field of a prior query. |
before |
string | Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries specifying broadcaster_id or game_id. The cursor value specified here is from the pagination response field of a prior query. |
ended_at |
string | Ending date/time for returned clips, in RFC3339 format. (Note that the seconds value is ignored.) If this is specified, started_at also must be specified; otherwise, the time period is ignored. |
first |
integer | Maximum number of objects to return. Maximum: 100. Default: 20. |
started_at |
string | Starting date/time for returned clips, in RFC3339 format. (The seconds value is ignored.) If this is specified, ended_at also should be specified; otherwise, the ended_at date/time will be 1 week after the started_at value. |
Response Fields
| Field | Type | Description |
|---|---|---|
id |
string | ID of the clip being queried. |
url |
string | URL where the clip can be viewed. |
embed_url |
string | URL to embed the clip. |
broadcaster_id |
string | User ID of the stream from which the clip was created. |
broadcaster_name |
string | Display name corresponding to broadcaster_id. |
creator_id |
string | ID of the user who created the clip. |
creator_name |
string | Display name corresponding to creator_id. |
video_id |
string | ID of the video from which the clip was created. |
game_id |
string | ID of the game assigned to the stream when the clip was created. |
language |
string | Language of the stream from which the clip was created. A language value is either the ISO 639-1 two-letter code for a supported stream language or “other”. |
title |
string | Title of the clip. |
view_count |
int | Number of times the clip has been viewed. |
created_at |
string | Date when the clip was created. |
thumbnail_url |
string | URL of the clip thumbnail. |
duration |
float | Duration of the Clip in seconds (up to 0.1 precision). |
pagination |
object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. |
Example Request #1
This gets information for clip AwkwardHelplessSalamanderSwiftRage.
curl -X GET 'https://api.twitch.tv/helix/clips?id=AwkwardHelplessSalamanderSwiftRage' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response #1
{
"data": [
{
"id": "AwkwardHelplessSalamanderSwiftRage",
"url": "https://clips.twitch.tv/AwkwardHelplessSalamanderSwiftRage",
"embed_url": "https://clips.twitch.tv/embed?clip=AwkwardHelplessSalamanderSwiftRage",
"broadcaster_id": "67955580",
"broadcaster_name": "ChewieMelodies",
"creator_id": "53834192",
"creator_name": "BlackNova03",
"video_id": "205586603",
"game_id": "488191",
"language": "en",
"title": "babymetal",
"view_count": 10,
"created_at": "2017-11-30T22:34:18Z",
"thumbnail_url": "https://clips-media-assets.twitch.tv/157589949-preview-480x272.jpg",
"duration": 60
}
]
}
Example Request #2
This gets the top 5 clips from broadcaster 1234.
curl -X GET 'https://api.twitch.tv/helix/clips?broadcaster_id=1234&first=5' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response #2
{
"data": [
{
"id": "RandomClip1",
"url": "https://clips.twitch.tv/AwkwardHelplessSalamanderSwiftRage",
"embed_url": "https://clips.twitch.tv/embed?clip=RandomClip1",
"broadcaster_id": "1234",
"broadcaster_name": "JJ",
"creator_id": "123456",
"creator_name": "MrMarshall",
"video_id": "1234567",
"game_id": "33103",
"language": "en",
"title": "random1",
"view_count": 10,
"created_at": "2017-11-30T22:34:18Z",
"thumbnail_url": "https://clips-media-assets.twitch.tv/157589949-preview-480x272.jpg",
"duration": 12.9
},
...
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjoiIn0"
}
}
Get Code Status
✎Gets the status of one or more provided codes. This API requires that the caller is an authenticated Twitch user. The API is throttled to one request per second per authenticated user. Codes are redeemable alphanumeric strings tied only to the bits product. This third-party API allows other parties to redeem codes on behalf of users. Third-party app and extension developers can use the API to provide rewards of bits from within their games.
We provide sets of codes to the third party as part of a contract agreement. The third-party program then calls this API to credit a Twitch user by submitting any specific codes. This means that a bits reward can be applied without users having to follow any manual steps.
All codes are single-use. Once a code has been redeemed, via either this API or the site page, then the code is no longer valid for any further use.
URL
GET https://api.twitch.tv/helix/entitlements/codes
Authentication
Access is controlled via an app access token on the calling service. The client ID associated with the app access token must be approved by Twitch as part of a contracted arrangement.
Authorization
Callers with an app access token are authorized to redeem codes on behalf of any Twitch user account.
Query Parameters
| Param | Type | Description |
code |
String | The code to get the status of. Repeat this query parameter additional times to get the status of multiple codes. Ex: ?code=code1&code=code21-20 code parameters are allowed. |
user_id |
Integer | Represents a numeric Twitch user ID. The user account which is going to receive the entitlement associated with the code. |
Return Values
| Param | Type | Description |
data |
Array of payloads each of which includes code (string) and status (string). |
Indicates the current status of each key when checking key status. Indicates the success or error state of each key when redeeming. |
Code Statuses
| Code | Description |
SUCCESSFULLY_REDEEMED |
Request successfully redeemed this code to the authenticated user’s account.This status will only ever be encountered when calling the POST API to redeem a key. |
ALREADY_CLAIMED |
Code has already been claimed by a Twitch user. |
EXPIRED |
Code has expired and can no longer be claimed. |
USER_NOT_ELIGIBLE |
User is not eligible to redeem this code. |
NOT_FOUND |
Code is not valid and/or does not exist in our database. |
INACTIVE |
Code is not currently active. |
UNUSED |
Code has not been claimed.This status will only ever be encountered when calling the GET API to get a keys status. |
INCORRECT_FORMAT |
Code was not properly formatted. |
INTERNAL_ERROR |
Indicates some internal and/or unknown failure handling this code. |
Example Request
curl -X GET 'https://api.twitch.tv/helix/entitlements/codes?code=KUHXV-4GXYP-AKAKK&code=XZDDZ-5SIQR-RT5M3&user_id=156900877' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data":[
{
"code":"KUHXV-4GXYP-AKAKK",
"status":"UNUSED"
},
{
"code":"XZDDZ-5SIQR-RT5M3",
"status":"ALREADY_CLAIMED"
}
]
}
Get Drops Entitlements
✎Gets a list of entitlements for a given organization that have been granted to a game, user, or both.
Authentication
App Access OAuth Token required.
Authorization
OAuth Token Client ID must have ownership of Game:
Client ID>Organization ID>Game ID
Pagination support
Forward only
URL
GET https://api.twitch.tv/helix/entitlements/drops
Required Query Parameters
None
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
id |
string | Unique Identifier of the entitlement |
user_id |
string | A Twitch User ID |
game_id |
string | A Twitch Game ID |
after |
string | The cursor used to fetch the next page of data. |
first |
integer | Maximum number of entitlements to return. Default: 20 Max: 1000 |
Valid combinations of requests are:
| Authorization Provided | Request Fields Present | Data Returned |
|---|---|---|
| App Access OAuth Token |
No fields | All entitlements with benefits owned by your organization. |
user_id |
All entitlements for a user with benefits owned by your organization. | |
user_id, game_id |
All entitlements for the game granted to a user. Your organization must own the game. | |
game_id |
All entitlements for all users for a game. Your organization must own the game. | |
| User OAuth Token | No fields | All entitlements owned by that user with benefits owned by your organization. |
user_id |
Invalid | |
user_id, game_id |
Invalid | |
game_id |
All entitlements owned by a user for the specified game. Your organization must own the game. |
Return Values
| Parameter | Type | Description |
|---|---|---|
data |
array | Array of entitlements |
id |
string | Unique Identifier of the entitlement |
benefit_id |
string | Identifier of the Benefit |
timestamp |
string | UTC timestamp in ISO format when this entitlement was granted on Twitch. |
user_id |
string | Twitch User ID of the user who was granted the entitlement. |
game_id |
string | Twitch Game ID of the game that was being played when this benefit was entitled. |
pagination |
object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. |
Response Codes
| HTTP Code | Meaning |
|---|---|
| 200 OK | Resource found |
| 400 Bad Request |
|
| 401 Unauthorized |
|
| 429 Rate Limit | API will handle rate limiting |
| 500 Internal Server Error | |
| 503 Service Unavailable |
Example Request
curl -H GET 'helix/entitlements/drops?user_id=25009227&game_id=33214' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "fb78259e-fb81-4d1b-8333-34a06ffc24c0",
"benefit_id": "74c52265-e214-48a6-91b9-23b6014e8041",
"timestamp": "2019-01-28T04:17:53.325Z",
"user_id": "25009227",
"game_id": "33214"
},
{
"id": "862750a5-265e-4ab6-9f0a-c64df3d54dd0",
"benefit_id": "74c52265-e214-48a6-91b9-23b6014e8041",
"timestamp": "2019-01-28T04:16:53.325Z",
"user_id": "25009227",
"game_id": "33214"
},
{
"id": "d8879baa-3966-4d10-8856-15fdd62cce02",
"benefit_id": "cdfdc5c3-65a2-43bc-8767-fde06eb4ab2c",
"timestamp": "2019-01-28T04:15:53.325Z",
"user_id": "25009227",
"game_id": "33214"
},
...
],
"pagination": {
"cursor": "eyJiIjpudW..."
}
}
Redeem Code
✎Redeems one or more provided codes to the authenticated Twitch user. This API requires that the caller is an authenticated Twitch user. This API requires that the caller is an authenticated Twitch user. The API is throttled to one request per second per authenticated user. Codes are redeemable alphanumeric strings tied only to the bits product. This third-party API allows other parties to redeem codes on behalf of users. Third-party app and extension developers can use the API to provide rewards of bits from within their games. We provide sets of codes to the third party as part of a contract agreement. The third-party program then calls this API to credit the Twitch user by submitting any specific codes. This means that a bits reward can be applied without the user having to follow any manual steps.
All codes are single-use. Once a code has been redeemed, via either this API or the site page, the code is no longer valid for any further use.
URL
POST https://api.twitch.tv/helix/entitlements/codes
Authentication
Access is controlled via an app access token on the calling service. The client ID associated with the app access token must be approved by Twitch.
Authorization
Callers with an app access token are authorized to redeem codes on behalf of any Twitch user account.
Query Parameters
| Parameter | Type | Description |
code |
String | The code to redeem to the authenticated user’s account. A fifteen character (plus optional hyphen separators) alphanumeric string, e.g. ABCDE-12345-FGHIJ Repeat this query parameter additional times to redeem multiple codes. Ex: ?code=code1&code=code21-20 code parameters are allowed. |
user_id |
Integer | Represents a numeric Twitch user ID. The user account which is going to receive the entitlement associated with the code. |
Return Values
| Parameter | Type | Description |
data |
Array of payloads each of which includes code (string) and status (string). |
Indicates the success or error state of each key when redeeming. |
Code Statuses
| Code | Description |
SUCCESSFULLY_REDEEMED |
Request successfully redeemed this code to the authenticated user’s account. This status will only ever be encountered when calling the POST API to redeem a key. |
ALREADY_CLAIMED |
Code has already been claimed by a Twitch user. |
EXPIRED |
Code has expired and can no longer be claimed. |
USER_NOT_ELIGIBLE |
User is not eligible to redeem this code. |
NOT_FOUND |
Code is not valid and/or does not exist in our database. |
INACTIVE |
Code is not currently active. |
UNUSED |
Code has not been claimed. This status will only ever be encountered when calling the GET API to get a key’s status. |
INCORRECT_FORMAT |
Code was not properly formatted. |
INTERNAL_ERROR |
Indicates some internal and/or unknown failure handling this code. |
Example Request
curl -X POST 'https://api.twitch.tv/helix/entitlements/codes?code=8CD5P-V3J92-2S6JY&code=PUN4G-HYFVP-MMFET' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data":[
{
"code":"8CD5P-V3J92-2S6JY",
"status":"SUCCESSFULLY_REDEEMED"
},
{
"code":"PUN4G-HYFVP-MMFET",
"status":"ALREADY_CLAIMED"
}
]
}
Create EventSub Subscription
✎Creates an EventSub subscription.
Authentication
- App Access Token
URL
POST https://api.twitch.tv/helix/eventsub/subscriptions
Required Query Parameters
None
Required Body Parameters
| Parameter | Type | Description |
|---|---|---|
type |
string | The category of the subscription that is being created. Valid subscription types can be found here. |
version |
string | The version of the subscription type that is being created. Each subscription type has independent versioning. |
condition |
condition | JSON object containing custom parameters for a particular subscription. |
transport |
transport | JSON object containing notification delivery specific configuration including a method string. Valid transport methods include: webhook. In addition to the method string, a webhook transport must include the callback and secret information. |
Response Fields
| Field | Type | Description |
|---|---|---|
data |
array | Array containing 1 element: the created subscription. |
id |
string | ID of the subscription created. |
status |
string | Status of the subscription. Valid values are: enabled: designates that the subscription is in an operable state and is valid. webhook_callback_verification_pending: webhook is pending verification of the callback specified in the subscription creation request. webhook_callback_verification_failed: webhook failed verification of the callback specified in the subscription creation request. notification_failures_exceeded: notification delivery failure rate was too high. authorization_revoked: authorization for user(s) in the condition was revoked. user_removed: a user in the condition of the subscription was removed. |
type |
string | The category of the subscription that was created. |
version |
string | The version of the subscription type that was created. |
condition |
condition | JSON object specifying custom parameters for the subscription. |
created_at |
string | RFC3339 timestamp indicating when the subscription was created. |
transport |
transport | JSON object indicating the notification delivery specific information. Includes the transport method and callback URL. |
total |
integer | Total number of subscriptions for the client ID that made the subscription creation request. |
total_cost |
integer | Total cost of all the subscriptions for the client ID that made the subscription creation request. |
max_total_cost |
integer | The maximum total cost allowed for all of the subscriptions for the client ID that made the subscription creation request. |
Example Request
.
curl -X POST 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
-d '{"type":"users.update","version":"1","condition":{"user_id":"1234"},"transport":{"method":"webhook","callback":"https://this-is-a-callback.com","secret":"s3cre7"}}'
Example Response
{
"data": [
{
"id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
"status": "webhook_callback_verification_pending",
"type": "users.update",
"version": "1",
"condition": {
"user_id": "1234"
},
"created_at": "2020-11-10T20:29:44Z",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback.com"
},
"cost": 1
}
],
"total": 1,
"total_cost": 1,
"max_total_cost": 10000
}
Delete EventSub Subscription
✎Delete an EventSub subscription.
Authentication
- App Access Token
URL
DELETE https://api.twitch.tv/helix/eventsub/subscriptions
Required Query Parameters
| Name | Type | Description |
|---|---|---|
id |
string | The subscription ID for the subscription you want to delete. |
Response Fields
None
Response Codes
| Code | Meaning |
|---|---|
| 204 | Subscription deleted successfully. |
Example Request
Deletes an EventSub subscription.
curl -X DELETE 'https://api.twitch.tv/helix/eventsub/subscriptions?id=26b1c993-bfcf-44d9-b876-379dacafe75a' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
Example Response
204 No Content
Get EventSub Subscriptions
✎Get a list of your EventSub subscriptions. The subscriptions are paginated and ordered by most recent first.
Authentication
- App Access Token
URL
GET https://api.twitch.tv/helix/eventsub/subscriptions
Required Query Parameters
None
Optional Query Parameters
Use parameters to filter by subscription status or type. Only include one filter query parameter; if you specify both status and type parameters, you will receive an error response.
| Parameter | Type | Description |
|---|---|---|
status |
string | Include this parameter to filter subscriptions by one status type. Valid values: enabled: the subscription is in an operable state and is valid. webhook_callback_verification_pending: subscription is pending verification of the callback specified in the subscription creation request. webhook_callback_verification_failed: subscription failed verification of the callback specified in the subscription creation request. notification_failures_exceeded: notification delivery failure rate was too high. authorization_revoked: authorization for user(s) in the condition was revoked. user_removed: a user in the condition of the subscription was removed. |
type |
string | Include this parameter to filter subscriptions by subscription type name (e.g., channel.update). |
Response Fields
| Field | Type | Description |
|---|---|---|
data |
array | Array containing subscriptions. |
id |
string | ID of the subscription. |
status |
string | Status of the subscription. Valid values are: enabled: designates that the subscription is in an operable state and is valid. webhook_callback_verification_pending: webhook is pending verification of the callback specified in the subscription creation request. webhook_callback_verification_failed: webhook failed verification of the callback specified in the subscription creation request. notification_failures_exceeded: notification delivery failure rate was too high. authorization_revoked: authorization for user(s) in the condition was revoked. user_removed: a user in the condition of the subscription was removed. |
type |
string | The category of the subscription. |
version |
string | The version of the subscription. |
condition |
condition | JSON object specifying custom parameters for the subscription. |
created_at |
string | RFC3339 timestamp indicating when the subscription was created. |
transport |
transport | JSON object indicating the notification delivery specific information. Includes the transport method and callback URL. |
total |
integer | Total number of subscriptions for the client ID that made the subscription creation request. |
total_cost |
integer | Total cost of all the subscriptions for the client ID that made the subscription creation request. |
max_total_cost |
integer | The maximum total cost allowed for all of the subscriptions for the client ID that made the subscription creation request. |
pagination |
object | A cursor value to be used in a subsequent request to specify the starting point of the next set of results. |
Example Request
Get a list of your EventSub subscriptions. The subscriptions are paginated and ordered by most recent first.
curl -X GET 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
Example Response
{
"total": 2,
"data": [
{
"id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
"status": "enabled",
"type": "streams.online",
"version": "1",
"condition": {
"broadcaster_user_id": "1234"
},
"created_at": "2020-11-10T20:08:33Z",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback.com"
},
"cost": 1
},
{
"id": "35016908-41ff-33ce-7879-61b8dfc2ee16",
"status": "webhook-callback-verification-pending",
"type": "users.update",
"version": "1",
"condition": {
"user_id": "1234"
},
"created_at": "2020-11-10T20:31:52Z",
"transport": {
"method": "webhook",
"callback": "https://this-is-a-callback.com"
},
"cost": 0
}
],
"total_cost": 1,
"max_total_cost": 10000,
"pagination": {}
}
Get Top Games
✎Gets games sorted by number of current viewers on Twitch, most popular first.
The response has a JSON payload with a data field containing an array of games information elements and a pagination field containing information required to query for more streams.
Authentication
OAuth or App Access Token required.
URL
GET https://api.twitch.tv/helix/games/top
Required Query Parameters
None
Optional Query Parameters
| Name | Type | Description |
|---|---|---|
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
before |
string | Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
first |
integer | Maximum number of objects to return. Maximum: 100. Default: 20. |
Response Fields
| Field | Type | Description |
|---|---|---|
box_art_url |
object | Template URL for a game’s box art. |
id |
string | Game ID. |
name |
string | Game name. |
pagination |
object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. |
Example Request
This gets the 20 currently most-viewed games.
curl -X GET 'https://api.twitch.tv/helix/games/top' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "493057",
"name": "PLAYERUNKNOWN'S BATTLEGROUNDS",
"box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/PLAYERUNKNOWN%27S%20BATTLEGROUNDS-{width}x{height}.jpg"
},
...
],
"pagination":{"cursor":"eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6MjB9fQ=="}
}
Get Games
✎Gets game information by game ID or name.
The response has a JSON payload with a data field containing an array of games elements.
Authentication
OAuth or App Access Token required.
URL
GET https://api.twitch.tv/helix/games
Required Query Parameters
| Name | Type | Description |
|---|---|---|
id |
string | Game ID. At most 100 id values can be specified. |
name |
string | Game name. The name must be an exact match. For example, “Pokemon” will not return a list of Pokemon games; instead, query any specific Pokemon games in which you are interested. At most 100 name values can be specified. |
For a query to be valid, name and/or id must be specified.
Optional Query Parameters
None
Response Fields
| Fields | Type | Description |
|---|---|---|
box_art_url |
object | Template URL for the game’s box art. |
id |
string | Game ID. |
name |
string | Game name. |
Example Request
This gets information for game ID 493057.
curl -X GET 'https://api.twitch.tv/helix/games?id=493057' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/Fortnite-52x72.jpg",
"id": "33214",
"name": "Fortnite"
}
... ],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN"
}
}
Get Hype Train Events
✎Description
Gets the information of the most recent Hype Train of the given channel ID. When there is currently an active Hype Train, it returns information about that Hype Train. When there is currently no active Hype Train, it returns information about the most recent Hype Train. After 5 days, if no Hype Train has been active, the endpoint will return an empty response.
Authentication
- User OAuth Token
- Required scope:
channel:read:hype_train
URL
GET https://api.twitch.tv/helix/hypetrain/events
Required Query Parameter
| Parameter | Type | Description |
broadcaster_id |
string | User ID of the broadcaster. Must match the User ID in the Bearer token if User Token is used. |
Optional Query Parameters
| Parameter | Type | Description |
first |
integer | Maximum number of objects to return. Maximum: 100. Default: 1. |
id |
string | The id of the wanted event, if known |
cursor |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without id. If an ID is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query. |
Return Values
| Parameter | Type | Description |
id |
string | The distinct ID of the event |
event_type |
string | Displays hypetrain.{event_name}, currently only hypetrain.progression |
event_timestamp |
string | RFC3339 formatted timestamp of event |
version |
string | Returns the version of the endpoint |
event_data |
object | (See below for the schema) |
id |
string | The distinct ID of this Hype Train |
broadcaster_id |
string | Channel ID of which Hype Train events the clients are interested in |
started_at |
string | RFC3339 formatted timestamp of when this Hype Train started |
expires_at |
string | RFC3339 formatted timestamp of the expiration time of this Hype Train |
cooldown_end_time |
string | RFC3339 formatted timestamp of when another Hype Train can be started again |
level |
integer | The highest level (in the scale of 1-5) reached of the Hype Train |
goal |
integer | The goal value of the level above |
total |
integer | The total score so far towards completing the level goal above |
top_contributions |
object | An array of top contribution objects, one object for each type. For example, one object would represent top contributor of BITS, by aggregate, and one would represent top contributor of SUBS by count. |
total |
integer | Total aggregated amount of all contributions by the top contributor. If type is BITS, total represents aggregate amount of bits used. If type is SUBS, aggregate total where 500, 1000, or 2500 represent tier 1, 2, or 3 subscriptions respectively. For example, if top contributor has gifted a tier 1, 2, and 3 subscription, total would be 4000. |
type |
string | Identifies the contribution method, either BITS or SUBS |
user |
string | ID of the contributing user |
last_contribution |
object | An object that represents the most recent contribution |
total |
integer | Total amount contributed. If type is BITS, total represents amounts of bits used. If type is SUBS, total is 500, 1000, or 2500 to represent tier 1, 2, or 3 subscriptions respectively |
type |
string | Identifies the contribution method, either BITS or SUBS |
user |
string | ID of the contributing user |
pagination |
string | A cursor value, to be used in a subsequent requests to specify the starting point of the next set of results |
Example Request
curl -X GET
'https://api.twitch.tv/helix/hypetrain/events?broadcaster_id=270954519&first=1' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "1b0AsbInCHZW2SQFQkCzqN07Ib2",
"event_type": "hypetrain.progression",
"event_timestamp": "2020-04-24T20:07:24Z",
"version": "1.0",
"event_data": {
"broadcaster_id": "270954519",
"cooldown_end_time": "2020-04-24T20:13:21.003802269Z",
"expires_at": "2020-04-24T20:12:21.003802269Z",
"goal": 1800,
"id": "70f0c7d8-ff60-4c50-b138-f3a352833b50",
"last_contribution": {
"total": 200,
"type": "BITS",
"user": "134247454"
},
"level": 2,
"started_at": "2020-04-24T20:05:47.30473127Z",
"top_contributions": [
{
"total": 600,
"type": "BITS",
"user": "134247450"
}
],
"total": 600
}
}
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjI3MDk1NDUxOToxNTg3NzU4ODQ0OjFiMEFzYkluQ0haVzJTUUZRa0N6cU4wN0liMiJ9fQ"
}
}
Check AutoMod Status
✎Determines whether a string message meets the channel’s AutoMod requirements.
AutoMod is a moderation tool that blocks inappropriate or harassing chat with powerful moderator control. AutoMod detects misspellings and evasive language automatically. AutoMod uses machine learning and natural language processing algorithms to hold risky messages from chat so they can be reviewed by a channel moderator before appearing to other viewers in the chat. Moderators can approve or deny any message caught by AutoMod.
For more information about AutoMod, see How to Use AutoMod.
Authorization
- OAuth token required
- Required Scope:
moderation:read
URL
POST https://api.twitch.tv/helix/moderation/enforcements/status
Pagination Support
None.
Query Parameter
| Parameter | Required | Type | Description |
broadcaster_id |
yes | string | Provided broadcaster_id must match the user_id in the auth token. |
Body Parameters
| Parameter | Required | Type | Description |
msg_id |
yes | string | Developer-generated identifier for mapping messages to results. |
msg_text |
yes | string | Message text. |
user_id |
yes | string | User ID of the sender. |
Return Values
| Parameter | Type | Description |
msg_id |
string | The msg_id passed in the body of the POST message. Maps each message to its status. |
is_permitted |
Boolean | Indicates if this message meets AutoMod requirements. |
Example Request
Checks to see if the messages “Hello World!” and “Boooooo!” meets AutoMod requirements.
curl -X POST 'https://api.twitch.tv/helix/moderation/enforcements/status' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-d '{
"data": [
{
"msg_id": "123",
"msg_text": "Hello World!",
"user_id": "23749"
},
{
"msg_id": "393",
"msg_text": "Boooooo!",
"user_id": "23422"
}
]
}'
Example Response
Shows that message ID 123 meets the requirements and message ID 393 does not.
{
"data": [
{
"msg_id": "123",
"is_permitted": true
},
{
"msg_id": "393",
"is_permitted": false
}
]
}
Manage Held AutoMod Messages
✎Allow or deny a message that was held for review by AutoMod.
In order to retrieve messages held for review, use the chat_moderator_actions topic via PubSub. For more information about AutoMod, see How to Use AutoMod.
Authorization
- User OAuth token required
- Required Scope:
moderator:manage:automod
Note that the scope allows this endpoint to be used for any channel that the authenticated user is a moderator, including their own channel.
URL
POST https://api.twitch.tv/helix/moderation/automod/message
Required Body Parameters
| Parameter | Type | Description |
user_id |
string | The moderator who is approving or rejecting the held message. Must match the user_id in the user OAuth token. |
msg_id |
string | ID of the message to be allowed or denied. These message IDs are retrieved from PubSub as mentioned above. Only one message ID can be provided. |
action |
string | The action to take for the message. Must be "ALLOW" or "DENY". |
Response Codes
| Code | Meaning |
|---|---|
| 204 | Message was approved or denied successfully. |
| 400 | Message was already processed or an invalid action was provided. |
| 401 | Authentication failure. |
| 403 | Requesting user is not authorized to process messages for this channel. |
| 404 | Message not found or invalid msg_id. |
Example Request 1
Allow a message being held by AutoMod.
curl -X POST 'https://api.twitch.tv/helix/moderation/automod/message' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-d '{
"user_id": "9327994",
"msg_id": "836013710",
"action": "ALLOW"
}'
Example Response 1
Shows that a message was successfully allowed.
204 No Content
Example Request 2
Deny a message being held by AutoMod.
curl -X POST 'https://api.twitch.tv/helix/moderation/automod/message' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-d '{
"user_id": "9327994",
"msg_id": "836013710",
"action": "DENY"
}'
Example Response 2
Shows that a message was successfully denied.
204 No Content
Get Banned Events
✎Returns all user bans and un-bans in a channel.
Authorization
- OAuth token required
- Required Scope:
moderation:read
URL
GET https://api.twitch.tv/helix/moderation/banned/events
Pagination Support
Forward pagination.
Required Query Parameter
| Parameter | Required | Type | Description |
broadcaster_id |
yes | string | Provided broadcaster_id must match the user_id in the auth token.Maximum: 1 |
Optional Query Parameters
| Parameter | Required | Type | Description |
user_id |
no | string | Filters the results and only returns a status object for ban events that include users being banned or un-banned in this channel and have a matching user_id. Format: Repeated Query Parameter, eg. /moderation/banned/events?broadcaster_id=1&user_id=2&user_id=3Maximum: 100 |
after |
no | string | Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without user_id. If a user_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query. |
first |
no | string | Maximum number of objects to return. Maximum: 100. Default: 20. |
Return Values
| Parameter | Type | Description |
id |
string | Event ID |
event_type |
string | Displays moderation.user.ban or moderation.user.unban |
event_timestamp |
string | RFC3339 formatted timestamp for events. |
pagination |
object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. |
version |
string | Returns the version of the endpoint. |
event_data |
strings | Returns broadcaster_id, broadcaster_login, broadcaster_name, user_id, user_login, user_name, and expires_at. |
Example Request
Returns all bans and un-bans for Broadcaster 198704263.
curl -X GET 'https://api.twitch.tv/helix/moderation/banned/events?broadcaster_id=198704263' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "1IPFqAb0p0JncbPSTEPhx8JF1Sa",
"event_type": "moderation.user.ban",
"event_timestamp": "2019-03-13T15:55:14Z",
"version": "1.0",
"event_data": {
"broadcaster_id": "198704263",
"broadcaster_login": "racageneg",
"broadcaster_name": "racageneg",
"user_id": "424596340",
"user_login": "quotrok",
"user_name": "quotrok",
"expires_at": ""
}
},
{
"id": "1IPFsDv5cs4mxfJ1s2O9Q5flf4Y",
"event_type": "moderation.user.unban",
"event_timestamp": "2019-03-13T15:55:30Z",
"version": "1.0",
"event_data": {
"broadcaster_id": "198704263",
"broadcaster_login": "racageneg",
"broadcaster_name": "racageneg",
"user_id": "424596340",
"user_login": "quotrok",
"user_name": "quotrok",
"expires_at": ""
}
},
{
"id": "1IPFqmlu9W2q4mXXjULyM8zX0rb",
"event_type": "moderation.user.ban",
"event_timestamp": "2019-03-13T15:55:19Z",
"version": "1.0",
"event_data": {
"broadcaster_id": "198704263",
"broadcaster_login": "racageneg",
"broadcaster_name": "racageneg",
"user_id": "424596340",
"user_login": "quotrok",
"user_name": "quotrok",
"expires_at": ""
}
}
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjE5OTYwNDI2MzoyMDIxMjA1MzE6MUlQRnFtbHU5VzJxNG1YWGpVTHlNOHpYMHJiIn19"
}
}
Get Banned Users
✎Returns all banned and timed-out users in a channel.
Authentication
- OAuth token required
- Required scope:
moderation:read
URL
GET https://api.twitch.tv/helix/moderation/banned
Pagination Support
Forward and reverse pagination.
Required Query Parameter
| Parameter | Required | Type | Description |
|---|---|---|---|
broadcaster_id | yes | string | Provided broadcaster_id must match the user_id in the auth token.Maximum: 1 |
Optional Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
user_id | no | string | Filters the results and only returns a status object for users who are banned in this channel and have a matching user_id. Format: Repeated Query Parameter, eg. /moderation/banned?broadcaster_id=1&user_id=2&user_id=3Maximum: 100 |
first | no | string | Maximum number of objects to return. Maximum: 100. Default: 20. |
after | no | string | Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without user_id. If a user_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query. |
before | no | string | Cursor for backward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without user_id. If a user_id is specified, it supersedes any cursor/offset. combinations. The cursor value specified here is from the pagination response field of a prior query. |
Return Values
| Parameter | Type | Description |
user_id |
string | User ID of a user who has been banned. |
user_login |
string | Login of a user who has been banned. |
user_name |
string | Display name of a user who has been banned. |
expires_at |
string | |
pagination |
object containing a string |
Example Request
Gets the users who have been banned by Broadcaster 198704263.
curl -X GET 'https://api.twitch.tv/helix/moderation/banned?broadcaster_id=198704263' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
Shows that users glowillig and quotrok have been banned.
{
"data": [
{
"user_id": "423374343",
"user_login": "glowillig",
"user_name": "glowillig",
"expires_at": "2019-03-15T02:00:28Z"
},
{
"user_id": "424596340",
"user_login": "quotrok",
"user_name": "quotrok",
"expires_at": "2018-08-07T02:07:55Z"
},
...
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
}
}
Get Moderators
✎Returns all moderators in a channel. Note: This endpoint does not return the broadcaster in the response, as broadcasters are channel owners and have all permissions of moderators implicitly.
Authorization
- OAuth token required
- Required scope:
moderation:read
URL
GET https://api.twitch.tv/helix/moderation/moderators
Pagination Support
Forward pagination only.
Required Query Parameter
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | Provided broadcaster_id must match the user_id in the auth token. Maximum: 1 |
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
user_id | string | Filters the results and only returns a status object for users who are moderators in this channel and have a matching user_id. Format: Repeated Query Parameter, eg. /moderation/moderators?broadcaster_id=1&user_id=2&user_id=3Maximum: 100 |
first | string | Maximum number of objects to return. Maximum: 100. Default: 20. |
after | string | Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without user_id. If a user_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query. |
Return Values
| Parameter | Type | Description |
user_id |
string | User ID of a moderator in the channel. |
user_login |
string | Login of a moderator in the channel. |
user_name |
string | Display name of a moderator in the channel. |
pagination |
object containing a string | A cursor value, to be used in subsequent requests to specify the starting point of the next set of results. |
Example Request
This request returns any moderators for Broadcaster ID 198704263.
curl -X GET 'https://api.twitch.tv/helix/moderation/moderators?broadcaster_id=198704263' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"user_id": "424596340",
"user_login": "quotrok",
"user_name": "quotrok"
},
...
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
}
}
Get Moderator Events
✎Returns a list of moderators or users added and removed as moderators from a channel.
Authorization
- OAuth token required
- Required scope:
moderation:read
URL
GET https://api.twitch.tv/helix/moderation/moderators/events
Pagination Support
Forward pagination only.
Required Query Parameter
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | Provided broadcaster_id must match the user_id in the auth token.Maximum: 1 |
Optional Query Parameter
| Parameter | Type | Description |
|---|---|---|
user_id |
string | Filters the results and only returns a status object for users who have been added or removed as moderators in this channel and have a matching user_id.Format: Repeated Query Parameter, e.g. /moderation/moderators/events?broadcaster_id=1&user_id=2&user_id=3Maximum: 100 |
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without user_id. If a user_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query. |
first |
string | Maximum number of objects to return. Maximum: 100. Default: 20. |
Return Values
| Parameter | Type | Description |
|---|---|---|
id |
string | User ID of the moderator. |
event_type |
string | Displays moderation.moderator.add or moderation.moderator.remove |
event_timestamp |
string | RFC3339 formatted timestamp for events. |
pagination |
object containing a string | A cursor value to be used in a subsequent request to specify the starting point of the next set of results. |
version |
string | Returns the version of the endpoint. |
broadcaster_id |
string | ID of the broadcaster adding or removing moderators. |
broadcaster_login |
string | Login of the broadcaster. |
broadcaster_name |
string | Name of the broadcaster. |
user_id |
string | ID of the user being added or removed as moderator. |
user_login |
string | Login of the user. |
user_name |
string | Name of the user. |
Example Request
Returns users added or removed as moderators for Broadcaster ID 198704263.
curl -X GET 'https://api.twitch.tv/helix/moderation/moderators/events?broadcaster_id=198704263' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "1IVBTnDSUDApiBQW4UBcVTK4hPr",
"event_type": "moderation.moderator.remove",
"event_timestamp": "2019-03-15T18:18:14Z",
"version": "1.0",
"event_data": {
"broadcaster_id": "198704263",
"broadcaster_login": "aan22209",
"broadcaster_name": "aan22209",
"user_id": "423374343",
"user_login": "glowillig",
"user_name": "glowillig"
}
},
{
"id": "1IVIPQdYIEnD8nJ376qkASDzsj7",
"event_type": "moderation.moderator.add",
"event_timestamp": "2019-03-15T19:15:13Z",
"version": "1.0",
"event_data": {
"broadcaster_id": "198704263",
"broadcaster_login": "aan22209",
"broadcaster_name": "aan22209",
"user_id": "423374343",
"user_login": "glowillig",
"user_name": "glowillig"
}
},
{
"id": "1IVBTP7gG61oXLMu7fvnRhrpsro",
"event_type": "moderation.moderator.remove",
"event_timestamp": "2019-03-15T18:18:11Z",
"version": "1.0",
"event_data": {
"broadcaster_id": "198704263",
"broadcaster_login": "aan22209",
"broadcaster_name": "aan22209",
"user_id": "424596340",
"user_login": "quotrok",
"user_name": "quotrok"
}
}
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
}
}
Get Polls
✎NEW Get information about all polls or specific polls for a Twitch channel. Poll information is available for 90 days.
Authorization
- User OAuth token
- Required scope:
channel:read:polls
URL
GET https://api.twitch.tv/helix/polls
Pagination Support
Forward pagination.
Required Query Parameter
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | The broadcaster running polls. Provided broadcaster_id must match the user_id in the user OAuth token.Maximum: 1 |
Optional Query Parameter
| Parameter | Type | Description |
|---|---|---|
id |
string | ID of a poll. Filters results to one or more specific polls. Not providing one or more IDs will return the full list of polls for the authenticated channel. Maximum: 100 |
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
first |
string | Maximum number of objects to return. Maximum: 20. Default: 20. |
Return Values
| Parameter | Type | Description |
|---|---|---|
id |
string | ID of the poll. |
broadcaster_id |
string | ID of the broadcaster. |
broadcaster_name |
string | Name of the broadcaster. |
broadcaster_login |
string | Login of the broadcaster. |
title |
string | Question displayed for the poll. |
choices |
object[] | Array of the poll choices. |
choice.id |
string | ID for the choice. |
choice.title |
string | Text displayed for the choice. |
choice.votes |
integer | Total number of votes received for the choice across all methods of voting. |
choice.channel_points_votes |
integer | Number of votes received via Channel Points. |
choice.bits_votes |
integer | Number of votes received via Bits. |
bits_voting_enabled |
boolean | Indicates if Bits can be used for voting. |
bits_per_vote |
integer | Number of Bits required to vote once with Bits. |
channel_points_voting_enabled |
boolean | Indicates if Channel Points can be used for voting. |
channel_points_per_vote |
integer | Number of Channel Points required to vote once with Channel Points. |
status |
string | Poll status. Valid values are:ACTIVE: Poll is currently in progress.COMPLETED: Poll has reached its ended_at time.TERMINATED: Poll has been manually terminated before its ended_at time.ARCHIVED: Poll is no longer visible on the channel.MODERATED: Poll is no longer visible to any user on Twitch.INVALID: Something went wrong determining the state. |
duration |
integer | Total duration for the poll (in seconds). |
started_at |
string | UTC timestamp for the poll’s start time. |
ended_at |
string | UTC timestamp for the poll’s end time. Set to null if the poll is active. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Poll details returned successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Returns information for a specific poll created for the TwitchDev channel.
curl -X GET 'https://api.twitch.tv/helix/polls?broadcaster_id=141981764&id=ed961efd-8a3f-4cf5-a9d0-e616c590cd2a' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
"broadcaster_id": "55696719",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"title": "Heads or Tails?",
"choices": [
{
"id": "4c123012-1351-4f33-84b7-43856e7a0f47",
"title": "Heads",
"votes": 0,
"channel_points_votes": 0,
"bits_votes": 0
},
{
"id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
"title": "Tails",
"votes": 0,
"channel_points_votes": 0,
"bits_votes": 0
}
],
"bits_voting_enabled": false,
"bits_per_vote": 0,
"channel_points_voting_enabled": false,
"channel_points_per_vote": 0,
"status": "ACTIVE",
"duration": 1800,
"started_at": "2021-03-19T06:08:33.871278372Z"
}
],
"pagination": {}
}
Create Poll
✎NEW Create a poll for a specific Twitch channel.
Authorization
- User OAuth token
- Required scope:
channel:manage:polls
URL
POST https://api.twitch.tv/helix/polls
Required Body Parameter
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | The broadcaster running polls. Provided broadcaster_id must match the user_id in the user OAuth token.Maximum: 1 |
title |
string | Question displayed for the poll. Maximum: 60 characters. |
choices |
object[] | Array of the poll choices. Minimum: 2 choices. Maximum: 5 choices. |
choice.title |
string | Text displayed for the choice. Maximum: 25 characters. |
duration |
integer | Total duration for the poll (in seconds). Minimum: 15. Maximum: 1800. |
Optional Body Parameter
| Parameter | Type | Description |
|---|---|---|
bits_voting_enabled |
boolean | Indicates if Bits can be used for voting. Default: false |
bits_per_vote |
integer | Number of Bits required to vote once with Bits. Minimum: 0. Maximum: 10000. |
channel_points_voting_enabled |
boolean | Indicates if Channel Points can be used for voting. Default: false |
channel_points_per_vote |
integer | Number of Channel Points required to vote once with Channel Points. Minimum: 0. Maximum: 1000000. |
Return Values
| Parameter | Type | Description |
|---|---|---|
id |
string | ID of the poll. |
broadcaster_id |
string | ID of the broadcaster. |
broadcaster_name |
string | Name of the broadcaster. |
broadcaster_login |
string | Login of the broadcaster. |
title |
string | Question displayed for the poll. |
choices |
object[] | Array of the poll choices. |
choice.id |
string | ID for the choice. |
choice.title |
string | Text displayed for the choice. |
choice.votes |
integer | Total number of votes received for the choice. |
choice.channel_points_votes |
integer | Number of votes received via Channel Points. |
choice.bits_votes |
integer | Number of votes received via Bits. |
bits_voting_enabled |
boolean | Indicates if Bits can be used for voting. |
bits_per_vote |
integer | Number of Bits required to vote once with Bits. |
channel_points_voting_enabled |
boolean | Indicates if Channel Points can be used for voting. |
channel_points_per_vote |
integer | Number of Channel Points required to vote once with Channel Points. |
status |
string | Poll status. Valid values are:ACTIVE: Poll is currently in progress.COMPLETED: Poll has reached its ended_at time.TERMINATED: Poll has been manually terminated before its ended_at time.ARCHIVED: Poll is no longer visible on the channel.MODERATED: Poll is no longer visible to any user on Twitch.INVALID: Something went wrong determining the state. |
duration |
integer | Total duration for the poll (in seconds). |
started_at |
string | UTC timestamp for the poll’s start time. |
ended_at |
string | UTC timestamp for the poll’s end time. Set to null if the poll is active. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Poll created successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Returns information for a specific poll created for the TwitchDev channel.
curl -X POST 'https://api.twitch.tv/helix/polls' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"broadcaster_id":"141981764",
"title":"Heads or Tails?",
"choices":[{
"title":"Heads"
},
{
"title":"Tails"
}],
"channel_points_voting_enabled":true,
"channel_points_per_vote":100,
"duration":1800
}'
Example Response
{
"data": [
{
"id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
"broadcaster_id": "141981764",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"title": "Heads or Tails?",
"choices": [
{
"id": "4c123012-1351-4f33-84b7-43856e7a0f47",
"title": "Heads",
"votes": 0,
"channel_points_votes": 0,
"bits_votes": 0
},
{
"id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
"title": "Tails",
"votes": 0,
"channel_points_votes": 0,
"bits_votes": 0
}
],
"bits_voting_enabled": false,
"bits_per_vote": 0,
"channel_points_voting_enabled": true,
"channel_points_per_vote": 100,
"status": "ACTIVE",
"duration": 1800,
"started_at": "2021-03-19T06:08:33.871278372Z"
}
]
}
End Poll
✎NEW End a poll that is currently active.
Authorization
- User OAuth token
- Required scope:
channel:manage:polls
URL
PATCH https://api.twitch.tv/helix/polls
Required Body Parameter
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | The broadcaster running polls. Provided broadcaster_id must match the user_id in the user OAuth token.Maximum: 1 |
id |
string | ID of the poll. |
status |
string | The poll status to be set. Valid values:TERMINATED: End the poll manually, but allow it to be viewed publicly.ARCHIVED: End the poll manually and do not allow it to be viewed publicly. |
Return Values
| Parameter | Type | Description |
|---|---|---|
id |
string | ID of the poll. |
broadcaster_id |
string | ID of the broadcaster. |
broadcaster_name |
string | Name of the broadcaster. |
broadcaster_login |
string | Login of the broadcaster. |
title |
string | Question displayed for the poll. |
choices |
object[] | Array of the poll choices. |
choice.id |
string | ID for the choice. |
choice.title |
string | Text displayed for the choice. |
choice.votes |
integer | Total number of votes received for the choice. |
choice.channel_points_votes |
integer | Number of votes received via Channel Points. |
choice.bits_votes |
integer | Number of votes received via Bits. |
bits_voting_enabled |
boolean | Indicates if Bits can be used for voting. |
bits_per_vote |
integer | Number of Bits required to vote once with Bits. |
channel_points_voting_enabled |
boolean | Indicates if Channel Points can be used for voting. |
channel_points_per_vote |
integer | Number of Channel Points required to vote once with Channel Points. |
status |
string | Poll Status. Valid values are:ACTIVE: Poll is currently in progress.COMPLETED: Poll has reached its ended_at time.TERMINATED: Poll has been manually terminated before its ended_at time.ARCHIVED: Poll is no longer visible on the channel.MODERATED: Poll is no longer visible to any user on Twitch.INVALID: Something went wrong determining the state. |
duration |
integer | Total duration for the poll (in seconds). |
started_at |
string | UTC timestamp for the poll’s start time. |
ended_at |
string | UTC timestamp for the poll’s end time. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Poll ended successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Ends a specific poll for the TwitchDev channel, but allows the results to be visible for viewers.
curl -X PATCH 'https://api.twitch.tv/helix/polls' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"broadcaster_id":"141981764",
"id":"ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
"status":"TERMINATED"
}'
Example Response
{
"data": [
{
"id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
"broadcaster_id": "141981764",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"title": "Heads or Tails?",
"choices": [
{
"id": "4c123012-1351-4f33-84b7-43856e7a0f47",
"title": "Heads",
"votes": 0,
"channel_points_votes": 0,
"bits_votes": 0
},
{
"id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
"title": "Tails",
"votes": 0,
"channel_points_votes": 0,
"bits_votes": 0
}
],
"bits_voting_enabled": false,
"bits_per_vote": 0,
"channel_points_voting_enabled": true,
"channel_points_per_vote": 100,
"status": "TERMINATED",
"duration": 1800,
"started_at": "2021-03-19T06:08:33.871278372Z",
"ended_at": "2021-03-19T06:11:26.746889614Z"
}
]
}
Get Predictions
✎NEW Get information about all Channel Points Predictions or specific Channel Points Predictions for a Twitch channel. Results are ordered by most recent, so it can be assumed that the currently active or locked Prediction will be the first item.
Authorization
- User OAuth token
- Required scope:
channel:read:predictions
URL
GET https://api.twitch.tv/helix/predictions
Pagination Support
Forward pagination.
Required Query Parameter
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | The broadcaster running Predictions. Provided broadcaster_id must match the user_id in the user OAuth token.Maximum: 1 |
Optional Query Parameter
| Parameter | Type | Description |
|---|---|---|
id |
string | ID of a Prediction. Filters results to one or more specific Predictions. Not providing one or more IDs will return the full list of Predictions for the authenticated channel. Maximum: 100 |
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
first |
string | Maximum number of objects to return. Maximum: 20. Default: 20. |
Return Values
| Parameter | Type | Description |
|---|---|---|
id |
string | ID of the Prediction. |
broadcaster_id |
string | ID of the broadcaster. |
broadcaster_name |
string | Name of the broadcaster. |
broadcaster_login |
string | Login of the broadcaster. |
title |
string | Title for the Prediction. |
winning_outcome_id |
string | ID of the winning outcome. If the status is ACTIVE, this is set to null. |
outcomes |
object[] | Array of possible outcomes for the Prediction. |
outcome.id |
string | ID for the outcome. |
outcome.title |
string | Text displayed for outcome. |
outcome.users |
integer | Number of unique uesrs that chose the outcome. |
outcome.channel_points |
integer | Number of Channel Points used for the outcome. |
outcome.top_predictors |
object[] | Array of users who were the top predictors. null if none. |
outcome.top_predictors.user.id |
string | ID of the user. |
outcome.top_predictors.user.name |
string | Display name of the user. |
outcome.top_predictors.user.login |
string | Login of the user. |
outcome.top_predictors.user.channel_points_used |
integer | Number of Channel Points used by the user. |
outcome.top_predictors.user.channel_points_won |
integer | Number of Channel Points won by the user. |
outcome.color |
string | Color for the outcome. Valid values: BLUE, PINK |
prediction_window |
integer | Total duration for the Prediction (in seconds). |
status |
string | Status of the Prediction. Valid values are:RESOLVED: A winning outcome has been chosen and the Channel Points have been distributed to the users who guessed the correct outcome.ACTIVE: The Prediction is active and viewers can make predictions.CANCELED: The Prediction has been canceled and the Channel Points have been refunded to participants.LOCKED: The Prediction has been locked and viewers can no longer make predictions. |
created_at |
string | UTC timestamp for the Prediction’s start time. |
ended_at |
string | UTC timestamp for when the Prediction ended. If the status is ACTIVE, this is set to null. |
locked_at |
string | UTC timestamp for when the Prediction was locked. If the status is not LOCKED, this is set to null. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Prediction details returned successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Returns information for a specific Prediction created for the TwitchDev channel.
curl -X GET 'https://api.twitch.tv/helix/predictions?broadcaster_id=55696719&id=d6676d5c-c86e-44d2-bfc4-100fb48f0656' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "d6676d5c-c86e-44d2-bfc4-100fb48f0656",
"broadcaster_id": "55696719",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"title": "Will there be any leaks today?",
"winning_outcome_id": null,
"outcomes": [
{
"id": "021e9234-5893-49b4-982e-cfe9a0aaddd9",
"title": "Yes",
"users": 0,
"channel_points": 0,
"top_predictors": null,
"color": "BLUE"
},
{
"id": "ded84c26-13cb-4b48-8cb5-5bae3ec3a66e",
"title": "No",
"users": 0,
"channel_points": 0,
"top_predictors": null,
"color": "PINK"
}
],
"prediction_window": 600,
"status": "ACTIVE",
"created_at": "2021-04-28T16:03:06.320848689Z",
"ended_at": null,
"locked_at": null
}
],
"pagination": {}
}
Create Prediction
✎NEW Create a Channel Points Prediction for a specific Twitch channel.
Authorization
- User OAuth token
- Required scope:
channel:manage:predictions
URL
POST https://api.twitch.tv/helix/predictions
Required Body Parameter
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | The broadcaster running Predictions. Provided broadcaster_id must match the user_id in the user OAuth token.Maximum: 1 |
title |
string | Title for the Prediction. Maximum: 45 characters. |
outcomes |
object[] | Array of outcome objects with titles for the Prediction. Array size must be 2. The first outcome object is the “blue” outcome and the second outcome object is the “pink” outcome when viewing the Prediction on Twitch. |
outcome.title |
string | Text displayed for the outcome choice. Maximum: 25 characters. |
prediction_window |
integer | Total duration for the Prediction (in seconds). Minimum: 1. Maximum: 1800. |
Return Values
| Parameter | Type | Description |
|---|---|---|
id |
string | ID of the Prediction. |
broadcaster_id |
string | ID of the broadcaster. |
broadcaster_login |
string | Login of the broadcaster. |
broadcaster_name |
string | Name of the broadcaster. |
title |
string | Title for the Prediction. |
winning_outcome_id |
string | ID of the winning outcome. |
outcomes |
object[] | Array of possible outcomes for the Prediction. |
outcome.id |
string | ID for the outcome. |
outcome.title |
string | Text displayed for outcome. |
outcome.users |
integer | Number of unique uesrs that chose the outcome. |
outcome.channel_points |
integer | Number of Channel Points used for the outcome. |
outcome.color |
string | Color for the outcome. Valid values: BLUE, PINK |
outcome.top_predictors |
object[] | Array of users who were the top predictors. |
outcome.top_predictors.user.id |
string | ID of the user. |
outcome.top_predictors.user.name |
string | Display name of the user. |
outcome.top_predictors.user.login |
string | Login of the user. |
outcome.top_predictors.user.channel_points_used |
integer | Number of Channel Points used by the user. |
outcome.top_predictors.user.channel_points_won |
integer | Number of Channel Points won by the user. |
prediction_window |
integer | Total duration for the Prediction (in seconds). |
status |
string | Status of the Prediction. Valid values are:RESOLVED: A winning outcome has been chosen and the Channel Points have been distributed to the users who predicted the correct outcome.ACTIVE: The Prediction is active and viewers can make predictions.CANCELED: The Prediction has been canceled and the Channel Points have been refunded to participants.LOCKED: The Prediction has been locked and viewers can no longer make predictions. |
created_at |
string | UTC timestamp for the Prediction’s start time. |
ended_at |
string | UTC timestamp for when the Prediction ended. If the status is ACTIVE, this is set to null. |
locked_at |
string | UTC timestamp for when the Prediction was locked. If the status is not LOCKED, this is set to null. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Prediction created successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Creates a Prediction for the TwitchDev channel.
curl -X POST 'https://api.twitch.tv/helix/predictions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
"broadcaster_id": "141981764",
"title": "Any leeks in the stream?",
"outcomes": [
{
"title": "Yes, give it time."
},
{
"title": "Definitely not."
}
],
"prediction_window": 120,
}'
Example Response
{
"data": [
{
"id": "bc637af0-7766-4525-9308-4112f4cbf178",
"broadcaster_id": "141981764",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"title": "Any leeks in the stream?",
"winning_outcome_id": null,
"outcomes": [
{
"id": "73085848-a94d-4040-9d21-2cb7a89374b7",
"title": "Yes, give it time.",
"users": 0,
"channel_points": 0,
"top_predictors": null,
"color": "BLUE"
},
{
"id": "906b70ba-1f12-47ea-9e95-e5f93d20e9cc",
"title": "Definitely not.",
"users": 0,
"channel_points": 0,
"top_predictors": null,
"color": "PINK"
}
],
"prediction_window": 120,
"status": "ACTIVE",
"created_at": "2021-04-28T17:11:22.595914172Z",
"ended_at": null,
"locked_at": null
}
]
}
End Prediction
✎NEW Lock, resolve, or cancel a Channel Points Prediction. Active Predictions can be updated to be “locked,” “resolved,” or “canceled.” Locked Predictions can be updated to be “resolved” or “canceled.”
Authorization
- User OAuth token
- Required scope:
channel:manage:predictions
URL
PATCH https://api.twitch.tv/helix/predictions
Required Body Parameter
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | The broadcaster running prediction events. Provided broadcaster_id must match the user_id in the user OAuth token.Maximum: 1 |
id |
string | ID of the Prediction. |
status |
string | The Prediction status to be set. Valid values:RESOLVED: A winning outcome has been chosen and the Channel Points have been distributed to the users who predicted the correct outcome.CANCELED: The Prediction has been canceled and the Channel Points have been refunded to participants.LOCKED: The Prediction has been locked and viewers can no longer make predictions. |
Optional Body Parameter
| Parameter | Type | Description |
|---|---|---|
winning_outcome_id |
string | ID of the winning outcome for the Prediction. This parameter is required if status is being set to RESOLVED. |
Return Values
| Parameter | Type | Description |
|---|---|---|
id |
string | ID of the prediction. |
broadcaster_id |
string | ID of the broadcaster. |
broadcaster_login |
string | Login of the broadcaster. |
broadcaster_name |
string | Name of the broadcaster. |
title |
string | Title for the prediction. |
winning_outcome_id |
string | ID of the winning outcome. |
outcomes |
object[] | Array of possible outcomes for the prediction. |
outcome.id |
string | ID for the outcome. |
outcome.title |
string | Text displayed for outcome. |
outcome.users |
integer | Number of unique uesrs that chose the outcome. |
outcome.channel_points |
integer | Number of Channel Points used for the outcome. |
outcome.color |
string | Color for the outcome. Valid values: BLUE, PINK |
outcome.top_predictors |
object[] | Array of users who were the top predictors. |
outcome.top_predictors.user.id |
string | ID of the user. |
outcome.top_predictors.user.name |
string | Display name of the user. |
outcome.top_predictors.user.login |
string | Login of the user. |
outcome.top_predictors.user.channel_points_used |
integer | Number of Channel Points used by the user. |
outcome.top_predictors.user.channel_points_won |
integer | Number of Channel Points won by the user. |
prediction_window |
integer | Total duration for the prediction (in seconds). |
status |
string | Status of the prediction. Valid values are:RESOLVED: A winning outcome has been chosen and the Channel Points have been distributed to the users who predicted the correct outcome.ACTIVE: The Prediction is active and viewers can make predictions.CANCELED: The Prediction has been canceled and the Channel Points have been refunded to participants.LOCKED: The Prediction has been locked and viewers can no longer make predictions. |
created_at |
string | UTC timestamp for the prediction’s start time. |
ended_at |
string | UTC timestamp for when the prediction ended. If the status is ACTIVE, this is set to null. |
locked_at |
string | UTC timestamp for when the prediction was locked. If the status is not LOCKED, this is set to null. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Prediction ended successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Ends a specific Prediction for the TwitchDev channel by setting the status to be resolved.
curl -X PATCH 'https://api.twitch.tv/helix/predictions' \ -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \ -H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \ -H 'Content-Type: application/json' \ -d '{
"broadcaster_id": "141981764",
"id": "bc637af0-7766-4525-9308-4112f4cbf178",
"status": "RESOLVED",
"winning_outcome_id": "73085848-a94d-4040-9d21-2cb7a89374b7"
}'
Example Response
{
"data": [
{
"id": "bc637af0-7766-4525-9308-4112f4cbf178",
"broadcaster_id": "141981764",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"title": "Will we win all the games?",
"winning_outcome_id": "73085848-a94d-4040-9d21-2cb7a89374b7",
"outcomes": [
{
"id": "73085848-a94d-4040-9d21-2cb7a89374b7",
"title": "yes",
"users": 0,
"channel_points": 0,
"top_predictors": null,
"color": "BLUE"
},
{
"id": "86010b2e-9764-4136-9359-fd1c9c5a8033",
"title": "no",
"users": 0,
"channel_points": 0,
"top_predictors": null,
"color": "PINK"
}
],
"prediction_window": 120,
"status": "RESOLVED",
"created_at": "2021-04-28T21:48:19.480371331Z",
"ended_at": "2021-04-28T21:54:24.026833954Z",
"locked_at": "2021-04-28T21:48:34.636685705Z"
}
]
}
Get Channel Stream Schedule
✎NEW Gets all scheduled broadcasts or specific scheduled broadcasts from a channel’s stream schedule. Scheduled broadcasts are defined as “stream segments” in the API.
Authorization
- User OAuth Token or App Access Token
URL
GET https://api.twitch.tv/helix/schedule
Pagination Support
Forward pagination.
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | User ID of the broadcaster who owns the channel streaming schedule. Provided broadcaster_id must match the user_id in the user OAuth token.Maximum: 1 |
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
id |
string | The ID of the stream segment to return. Maximum: 100. |
start_time |
string | A timestamp in RFC3339 format to start returning stream segments from. If not specified, the current date and time is used. |
utc_offset |
string | A timezone offset for the requester specified in minutes. This is recommended to ensure stream segments are returned for the correct week. For example, a timezone that is +4 hours from GMT would be “240.” If not specified, “0” is used for GMT. |
first |
integer | Maximum number of stream segments to return. Maximum: 25. Default: 20. |
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
Return Values
| Parameter | Type | Description |
|---|---|---|
segments |
array of objects | Scheduled broadcasts for this stream schedule. |
segment.id |
string | The ID for the scheduled broadcast. |
segment.start_time |
string | Scheduled start time for the scheduled broadcast in RFC3339 format. |
segment.end_time |
string | Scheduled end time for the scheduled broadcast in RFC3339 format. |
segment.title |
string | Title for the scheduled broadcast. |
segment.canceled_until |
string | Used with recurring scheduled broadcasts. Specifies the date of the next recurring broadcast in RFC3339 format if one or more specific broadcasts have been deleted in the series. Set to null otherwise. |
segment.category |
object | The category for the scheduled broadcast. Set to null if no category has been specified. |
segment.category.id |
string | Game/category ID. |
segment.category.name |
string | Game/category name. |
is_recurring |
boolean | Indicates if the scheduled broadcast is recurring weekly. |
broadcaster_id |
string | User ID of the broadcaster. |
broadcaster_name |
string | Display name of the broadcaster. |
broadcaster_login |
string | Login of the broadcaster. |
vacation |
object | If Vacation Mode is enabled, this includes start and end dates for the vacation. If Vacation Mode is disabled, value is set to null. |
vacation.start_time |
string | Start time for vacation specified in RFC3339 format. |
vacation.end_time |
string | End time for vacation specified in RFC3339 format. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Stream schedule events returned successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Returns all scheduled events from the TwitchDev channel’s stream schedule.
curl -X GET 'https://api.twitch.tv/helix/schedule?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": {
"segments": [
{
"id": "eyJzZWdtZW50SUQiOiJlNGFjYzcyNC0zNzFmLTQwMmMtODFjYS0yM2FkYTc5NzU5ZDQiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyNn0=",
"start_time": "2021-07-01T18:00:00Z",
"end_time": "2021-07-01T19:00:00Z",
"title": "TwitchDev Monthly Update // July 1, 2021",
"canceled_until": null,
"category": {
"id": "509670",
"name": "Science & Technology"
},
"is_recurring": false
},
...
],
"broadcaster_id": "141981764",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"vacation": null
},
"pagination": {}
}
Get Channel iCalendar
✎NEW Gets all scheduled broadcasts from a channel’s stream schedule as an iCalendar.
Authorization
- None. OAuth token and Client ID not required.
URL
GET https://api.twitch.tv/helix/schedule/icalendar
Pagination Support
None.
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | User ID of the broadcaster who owns the channel streaming schedule. Maximum: 1 |
Return Values
iCalendar data is returned according to RFC5545. The expected MIME type is text/calendar.
Response Codes
| Code | Meaning |
|---|---|
| 200 | iCalendar data returned successfully. |
| 400 | Request was invalid. |
Example Request
Returns all scheduled broadcasts from the TwitchDev channel’s stream schedule as an iCalendar.
curl -X GET 'https://api.twitch.tv/helix/schedule/icalendar?broadcaster_id=141981764'
Example Response
BEGIN:VCALENDAR
PRODID:-//twitch.tv//StreamSchedule//1.0
VERSION:2.0
CALSCALE:GREGORIAN
REFRESH-INTERVAL;VALUE=DURATION:PT1H
NAME:TwitchDev
BEGIN:VEVENT
UID:e4acc724-371f-402c-81ca-23ada79759d4
DTSTAMP:20210323T040131Z
DTSTART;TZID=/America/New_York:20210701T140000
DTEND;TZID=/America/New_York:20210701T150000
SUMMARY:TwitchDev Monthly Update // July 1, 2021
DESCRIPTION:Science & Technology.
CATEGORIES:Science & Technology
END:VEVENT
END:VCALENDAR%
Update Channel Stream Schedule
✎NEW Update the settings for a channel’s stream schedule. This can be used for setting vacation details.
Authorization
- User OAuth Token
- Required scope:
channel:manage:schedule
URL
PATCH https://api.twitch.tv/helix/schedule/settings
Pagination Support
None.
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | User ID of the broadcaster who owns the channel streaming schedule. Provided broadcaster_id must match the user_id in the user OAuth token.Maximum: 1 |
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
is_vacation_enabled |
boolean | Indicates if Vacation Mode is enabled. Set to true to add a vacation or false to remove vacation from the channel streaming schedule. |
vacation_start_time |
string | Start time for vacation specified in RFC3339 format. Required if is_vacation_enabled is set to true. |
vacation_end_time |
string | End time for vacation specified in RFC3339 format. Required if is_vacation_enabled is set to true. |
timezone |
string | The timezone for when the vacation is being scheduled using the IANA time zone database format. Required if is_vacation_enabled is set to true. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Stream schedule settings updated successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Enable Vacation Mode and specify vacation dates for the TwitchDev channel’s stream schedule.
curl -X PATCH 'https://api.twitch.tv/helix/schedule/settings?broadcaster_id=141981764&is_vacation_enabled=true&vacation_start_time=2021-05-16T00:00:00Z&vacation_end_time=2021-05-23T00:00:00Z&timezone=America/New_York' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
204 No Content
Create Channel Stream Schedule Segment
✎NEW Create a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule.
Authorization
- User OAuth Token
- Required scope:
channel:manage:schedule
URL
POST https://api.twitch.tv/helix/schedule/segment
Pagination Support
Forward pagination.
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | User ID of the broadcaster who owns the channel streaming schedule. Provided broadcaster_id must match the user_id in the user OAuth token.Maximum: 1 |
Required Body Parameters
| Parameter | Type | Description |
|---|---|---|
start_time |
string | Start time for the scheduled broadcast specified in RFC3339 format. |
timezone |
string | The timezone of the application creating the scheduled broadcast using the IANA time zone database format. |
is_recurring |
boolean | Indicates if the scheduled broadcast is recurring weekly. |
Optional Body Parameters
| Parameter | Type | Description |
|---|---|---|
duration |
string | Duration of the scheduled broadcast in minutes from the start_time.Default: 240. |
category_id |
string | Game/Category ID for the scheduled broadcast. |
title |
string | Title for the scheduled broadcast. Maximum: 140 characters. |
Return Values
| Parameter | Type | Description |
|---|---|---|
segments |
array of objects | Scheduled broadcasts for this stream schedule. |
segment.id |
string | The ID for the scheduled broadcast. |
segment.start_time |
string | Scheduled start time for the scheduled broadcast in RFC3339 format. |
segment.end_time |
string | Scheduled end time for the scheduled broadcast in RFC3339 format. |
segment.title |
string | Title for the scheduled broadcast. |
segment.canceled_until |
string | Used with recurring scheduled broadcasts. Specifies the date of the next recurring broadcast in RFC3339 format if one or more specific broadcasts have been deleted in the series. Set to null otherwise. |
segment.category |
object | The category for the scheduled broadcast. Set to null if no category has been specified. |
segment.category.id |
string | Game/category ID. |
segment.category.name |
string | Game/category name. |
is_recurring |
boolean | Indicates if the scheduled broadcast is recurring weekly. |
broadcaster_id |
string | User ID of the broadcaster. |
broadcaster_name |
string | Display name of the broadcaster. |
broadcaster_login |
string | Login of the broadcaster. |
vacation |
object | If Vacation Mode is enabled, this includes start and end dates for the vacation. If Vacation Mode is disabled, value is set to null. |
vacation.start_time |
string | Start time for vacation specified in RFC3339 format. |
vacation.end_time |
string | End time for vacation specified in RFC3339 format. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Stream schedule segment created successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Create a non-recurring stream schedule segment for the TwitchDev channel’s stream schedule.
curl -X POST 'https://api.twitch.tv/helix/schedule/segment?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
-d '{
"start_time": "2021-07-01T18:00:00Z",
"timezone": "America/New_York",
"is_recurring": false,
"duration": "60",
"category_id": "509670",
"title": "TwitchDev Monthly Update // July 1, 2021"
}'
Example Response
{
"data": {
"segments": [
{
"id": "eyJzZWdtZW50SUQiOiJlNGFjYzcyNC0zNzFmLTQwMmMtODFjYS0yM2FkYTc5NzU5ZDQiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyNn0=",
"start_time": "2021-07-01T18:00:00Z",
"end_time": "2021-07-01T19:00:00Z",
"title": "TwitchDev Monthly Update // July 1, 2021",
"canceled_until": null,
"category": {
"id": "509670",
"name": "Science & Technology"
},
"is_recurring": false
}
],
"broadcaster_id": "141981764",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"vacation": null
}
}
Update Channel Stream Schedule Segment
✎NEW Update a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule.
Authorization
- User OAuth Token
- Required scope:
channel:manage:schedule
URL
PATCH https://api.twitch.tv/helix/schedule/segment
Pagination Support
None.
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | User ID of the broadcaster who owns the channel streaming schedule. Provided broadcaster_id must match the user_id in the user OAuth token.Maximum: 1 |
id |
string | The ID of the streaming segment to update. Maximum: 1 |
Optional Body Parameters
| Parameter | Type | Description |
|---|---|---|
start_time |
string | Start time for the scheduled broadcast specified in RFC3339 format. |
duration |
string | Duration of the scheduled broadcast in minutes from the start_time.Default: 240. |
category_id |
string | Game/Category ID for the scheduled broadcast. |
title |
string | Title for the scheduled broadcast. Maximum: 140 characters. |
is_canceled |
boolean | Indicated if the scheduled broadcast is canceled. |
timezone |
string | The timezone of the application creating the scheduled broadcast using the IANA time zone database format. |
Return Values
| Parameter | Type | Description |
|---|---|---|
segments |
array of objects | Scheduled events for this stream schedule. |
segment.id |
string | The ID for the scheduled event. |
segment.start_time |
string | Scheduled start time for the scheduled event in RFC3339 format. |
segment.end_time |
string | Scheduled end time for the scheduled event in RFC3339 format. |
segment.title |
string | Title for the scheduled event. |
segment.canceled_until |
string | Used with recurring scheduled events. Specifies the date of the next recurring event in RFC3339 format if one or more specific events have been deleted in the series. Set to null otherwise. |
segment.category |
object | The category for the scheduled broadcast. Set to null if no category has been specified. |
segment.category.id |
string | Game/category ID. |
segment.category.name |
string | Game/category name. |
segment.is_recurring |
boolean | Indicates if the scheduled event is recurring. |
broadcaster_id |
string | User ID of the broadcaster. |
broadcaster_name |
string | Display name of the broadcaster. |
broadcaster_login |
string | Login of the broadcaster. |
vacation |
object | If Vacation Mode is enabled, this includes start and end dates for the vacation. If Vacation Mode is disabled, value is set to null. |
vacation.start_time |
string | Start time for vacation specified in RFC3339 format. |
vacation.end_time |
string | End time for vacation specified in RFC3339 format. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Stream schedule segment updated successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Update a non-recurring stream schedule segment for the TwitchDev channel’s stream schedule.
curl -X PATCH 'https://api.twitch.tv/helix/schedule/segment?broadcaster_id=141981764&id=eyJzZWdtZW50SUQiOiJlNGFjYzcyNC0zNzFmLTQwMmMtODFjYS0yM2FkYTc5NzU5ZDQiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyNn0=' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
-d '{
"duration": "120"
}'
Example Response
{
"data": {
"segments": [
{
"id": "eyJzZWdtZW50SUQiOiJlNGFjYzcyNC0zNzFmLTQwMmMtODFjYS0yM2FkYTc5NzU5ZDQiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyNn0=",
"start_time": "2021-07-01T18:00:00Z",
"end_time": "2021-07-01T20:00:00Z",
"title": "TwitchDev Monthly Update // July 1, 2021",
"canceled_until": null,
"category": {
"id": "509670",
"name": "Science & Technology"
},
"is_recurring": false
}
],
"broadcaster_id": "141981764",
"broadcaster_name": "TwitchDev",
"broadcaster_login": "twitchdev",
"vacation": null
}
}
Delete Channel Stream Schedule Segment
✎NEW Delete a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule.
Authorization
- User OAuth Token
- Required scope:
channel:manage:schedule
URL
DELETE https://api.twitch.tv/helix/schedule/segment
Pagination Support
None.
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | User ID of the broadcaster who owns the channel streaming schedule. Provided broadcaster_id must match the user_id in the user OAuth token.Maximum: 1 |
id |
string | The ID of the streaming segment to delete. |
Response Codes
| Code | Meaning |
|---|---|
| 204 | Stream schedule segment deleted successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Delete a non-recurring stream schedule segment for the TwitchDev channel’s stream schedule.
curl -X DELETE 'https://api.twitch.tv/helix/schedule/segment?broadcaster_id=141981764&id=eyJzZWdtZW50SUQiOiI4Y2EwN2E2NC0xYTZkLTRjYWItYWE5Ni0xNjIyYzNjYWUzZDkiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyMX0=' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
204 No Content
Search Categories
✎Returns a list of games or categories that match the query via name either entirely or partially.
Authentication
OAuth or App Access Token required
URL
GET https://api.twitch.tv/helix/search/categories
Pagination Support
Forward pagination only.
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
query |
string | URl encoded search query |
Optional Query Parameters
| Paramater | Type | Description |
|---|---|---|
first |
integer | Maximum number of objects to return. Maximum: 100. Default: 20. |
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
Return Values
| Parameter | Type | Description |
|---|---|---|
box_art_url |
string | Template URL for the game’s box art. |
name |
string | Game/category name. |
id |
string | Game/category ID. |
Note: The return values are the same as returned from GET https://api.twitch.tv/helix/games
Example Request
This request queries for games and categories.
curl -X GET 'https://api.twitch.tv/helix/search/categories?query=fort' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response
{
"data": [
{
"id": "33214",
"name": "Fortnite",
"box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/Fortnite-{width}x{height}.jpg"
},
...
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN"
}
}
Search Channels
✎Returns a list of channels (users who have streamed within the past 6 months) that match the query via channel name or description either entirely or partially. Results include both live and offline channels. Online channels will have additional metadata (e.g. started_at, tag_ids).
Authentication
OAuth or App Access Token required
Pagination Support
Forward only.
URL
GET helix/search/channels
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
query |
string | URl encoded search query |
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
first |
integer | Maximum number of objects to return. Maximum: 100 Default: 20 |
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
live_only |
Boolean | Filter results for live streams only. Default: false |
Return Values
| Parameter | Type | Description |
|---|---|---|
broadcaster_language |
string | Channel language (Broadcaster Language field from the Channels service). A language value is either the ISO 639-1 two-letter code for a supported stream language or “other”. |
broadcaster_login |
string | Login of the broadcaster. |
display_name |
string | Display name of the broadcaster. |
game_id |
string | ID of the game being played on the stream. |
game_name |
string | Name of the game being played on the stream. |
id |
string | Channel ID. |
is_live |
Boolean | Indicates if the channel is currenty live. |
tag_ids |
string[] | Tag IDs that apply to the stream. This array only contains strings when a channel is live. For all possibilities, see List of All Tags. Category Tags are not returned. |
thumbnail_url |
string | Thumbnail URL of the stream. All image URLs have variable width and height. You can replace {width} and {height} with any values to get that size image. |
title |
string | Stream title. |
started_at |
string | UTC timestamp. Returns an empty string if the channel is not live. |
Example Requests
This example searches for channels:
curl -X GET 'https://api.twitch.tv/helix/search/channels?query=loserfruit' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
This example searches for live channels:
curl -X GET 'https://api.twitch.tv/helix/search/channels?query=a_seagull' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Responses
Search for channels response:
{
"data": [
{
"broadcaster_language": "en",
"broadcaster_login": "loserfruit",
"display_name": "Loserfruit",
"game_id": "498000",
"game_name": "House Flipper",
"id": "41245072",
"is_live": false,
"tags_ids": [],
"thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/fd17325a-7dc2-46c6-8617-e90ec259501c-profile_image-300x300.png",
"title": "loserfruit",
"started_at": ""
},
...
],
"pagination": {
"cursor": "Mg=="
}
}
Search for live channels response:
{
"data": [
{
"broadcaster_language": "en",
"broadcaster_login": "a_seagull",
"display_name": "A_Seagull",
"game_id": "506442",
"game_name": "DOOM Eternal",
"id": "19070311",
"is_live": true,
"tags_ids": [
"6ea6bca4-4712-4ab9-a906-e3336a9d8039"
],
"thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/a_seagull-profile_image-4d2d235688c7dc66-300x300.png",
"title": "a_seagull",
"started_at": "2020-03-18T17:56:00Z"
}
],
"pagination": {}
}
Get Stream Key
✎Gets the channel stream key for a user.
Authentication
-
User OAuth token
-
Required scope:
channel:read:stream_key
URL
https://api.twitch.tv/helix/streams/key
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
broadcaster_id |
yes | string | User ID of the broadcaster |
Response Body
| Parameter | Type | Description |
|---|---|---|
stream_key |
string | Stream key for the channel |
Possible Response Codes
| HTTP Code | Meaning |
|---|---|
| 200 | Channel/Stream information returned successfully |
| 401 | Authentication failure |
| 500 | Internal Server Error, Failed to get channel information |
Example Request
curl -X GET 'https://api.twitch.tv/helix/streams/key' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"stream_key": "live_44322889_a34ub37c8ajv98a0"
},
]
}
Get Streams
✎Gets information about active streams. Streams are returned sorted by number of current viewers, in descending order. Across multiple pages of results, there may be duplicate or missing streams, as viewers join and leave streams.
The response has a JSON payload with a data field containing an array of stream information elements and a pagination field containing information required to query for more streams.
Authentication
OAuth or App Access Token required
URL
GET https://api.twitch.tv/helix/streams
Required Query Parameters
None
Optional Query Parameters
| Name | Type | Description |
|---|---|---|
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
before |
string | Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
first |
integer | Maximum number of objects to return. Maximum: 100. Default: 20. |
game_id |
string | Returns streams broadcasting a specified game ID. You can specify up to 100 IDs. |
language |
string | Stream language. You can specify up to 100 languages. A language value must be either the ISO 639-1 two-letter code for a supported stream language or “other”. |
user_id |
string | Returns streams broadcast by one or more specified user IDs. You can specify up to 100 IDs. |
user_login |
string | Returns streams broadcast by one or more specified user login names. You can specify up to 100 names. |
Response Fields
| Field | Type | Description |
|---|---|---|
id |
string | Stream ID. |
user_id |
string | ID of the user who is streaming. |
user_login |
string | Login of the user who is streaming. |
user_name |
string | Display name corresponding to user_id. |
game_id |
string | ID of the game being played on the stream. |
game_name |
string | Name of the game being played. |
type |
string | Stream type: "live" or "" (in case of error). |
title |
string | Stream title. |
viewer_count |
int | Number of viewers watching the stream at the time of the query. |
started_at |
string | UTC timestamp. |
language |
string | Stream language. A language value is either the ISO 639-1 two-letter code for a supported stream language or “other”. |
thumbnail_url |
string | Thumbnail URL of the stream. All image URLs have variable width and height. You can replace {width} and {height} with any values to get that size image |
tag_ids |
string | Shows tag IDs that apply to the stream. |
is_mature |
boolean | Indicates if the broadcaster has specified their channel contains mature content that may be inappropriate for younger audiences. |
pagination |
object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. |
Example Request #1
This gets information about the 20 most active streams.
curl -X GET 'https://api.twitch.tv/helix/streams' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response 1
{
"data": [
{
"id": "41375541868",
"user_id": "459331509",
"user_login": "auronplay",
"user_name": "auronplay",
"game_id": "494131",
"game_name": "Little Nightmares",
"type": "live",
"title": "hablamos y le damos a Little Nightmares 1",
"viewer_count": 78365,
"started_at": "2021-03-10T15:04:21Z",
"language": "es",
"thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_auronplay-{width}x{height}.jpg",
"tag_ids": [
"d4bb9c58-2141-4881-bcdc-3fe0505457d1"
],
"is_mature": false
},
...
],
"pagination": {
"cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19"
}
}
Example Request 2
This gets information about the next 20 most active streams, after the ones specified in the prior response. The request includes as its after value, the cursor returned in the prior response.
curl -X GET
'https://api.twitch.tv/helix/streams?first=20&after=eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response 2
{
"data": [
{
"id": "40944942733",
"user_id": "67931625",
"user_login": "amar",
"user_name": "Amar",
"game_id": "33214",
"game_name": "Fortnite",
"type": "live",
"title": "27h Stream Pringles Deathrun Map + 12k MK Turnier | !sub !JustLegends !Pc !yfood",
"viewer_count": 14944,
"started_at": "2021-03-09T16:59:39Z",
"language": "de",
"thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_amar-{width}x{height}.jpg",
"tag_ids": [
"9166ad14-41f1-4b04-a3b8-c8eb838c6be6"
],
"is_mature": false
},
],
"pagination": {
"cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam94TkRrME5DNDFOekV5TXpBMU1UWTVNRElzSW1RaU9tWmhiSE5sTENKMElqcDBjblZsZlE9PSJ9LCJhIjp7IkN1cnNvciI6ImV5SnpJam81TlRFMkxqVTNOREF6TmpNNU9UTXpNaXdpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In19"
}
}
Example Request 3
This gets information about three different specified streams using the ability to pass multiple logins. If a provided user is not live, they will not be included in the response.
curl -X GET
'https://api.twitch.tv/helix/streams?user_login=afro&user_login=cohhcarnage&user_login=lana_lux' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response 3
{
"data": [
{
"id": "40952121085",
"user_id": "101051819",
"user_login": "afro",
"user_name": "Afro",
"game_id": "32982",
"game_name": "Grand Theft Auto V",
"type": "live",
"title": "Jacob: Digital Den Laptops & Routers | NoPixel | !MAINGEAR !FCF",
"viewer_count": 1490,
"started_at": "2021-03-10T03:18:11Z",
"language": "en",
"thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_afro-{width}x{height}.jpg",
"tag_ids": [
"6ea6bca4-4712-4ab9-a906-e3336a9d8039"
],
"is_mature": false
},
...
],
"pagination": {}
}
Get Followed Streams
✎Gets information about active streams belonging to channels that the authenticated user follows. Streams are returned sorted by number of current viewers, in descending order. Across multiple pages of results, there may be duplicate or missing streams, as viewers join and leave streams.
Authentication
- OAuth user token required
- Required scope:
user:read:follows
URL
GET https://api.twitch.tv/helix/streams/followed
Required Query Parameters
| Name | Type | Description |
|---|---|---|
user_id |
string | Results will only include active streams from the channels that this Twitch user follows. user_id must match the User ID in the bearer token. |
Optional Query Parameters
| Name | Type | Description |
|---|---|---|
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
first |
integer | Maximum number of objects to return. Maximum: 100. Default: 100. |
Response Fields
| Field | Type | Description |
|---|---|---|
game_id |
string | ID of the game being played on the stream. |
game_name |
string | Name of the game being played. |
id |
string | Stream ID. |
language |
string | Stream language. A language value is either the ISO 639-1 two-letter code for a supported stream language or “other”. |
pagination |
object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. |
started_at |
string | UTC timestamp. |
tag_ids |
string | Shows tag IDs that apply to the stream. |
thumbnail_url |
string | Thumbnail URL of the stream. All image URLs have variable width and height. You can replace {width} and {height} with any values to get that size image |
title |
string | Stream title. |
type |
string | Stream type: "live" or "" (in case of error). |
user_id |
string | ID of the user who is streaming. |
user_login |
string | Login of the user who is streaming. |
user_name |
string | Display name corresponding to user_id. |
viewer_count |
int | Number of viewers watching the stream at the time of the query. |
Example Request
Retrieves the active streams for the channels that the TwitchDev user follows.
curl -X GET 'https://api.twitch.tv/helix/streams/followed?user_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response
{
"data": [
{
"id": "42170724654",
"user_id": "132954738",
"user_login": "aws",
"user_name": "AWS",
"game_id": "417752",
"game_name": "Talk Shows & Podcasts",
"type": "live",
"title": "AWS Howdy Partner! Y'all welcome ExtraHop to the show!",
"viewer_count": 20,
"started_at": "2021-03-31T20:57:26Z",
"language": "en",
"thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_aws-{width}x{height}.jpg",
"tag_ids": [
"6ea6bca4-4712-4ab9-a906-e3336a9d8039"
]
},
...
],
"pagination": {
"cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19"
}
}
Create Stream Marker
✎Creates a marker in the stream of a user specified by user ID. A marker is an arbitrary point in a stream that the broadcaster wants to mark; e.g., to easily return to later. The marker is created at the current timestamp in the live broadcast when the request is processed. Markers can be created by the stream owner or editors. The user creating the marker is identified by a Bearer token.
Markers cannot be created in some cases (an error will occur):
- If the specified user’s stream is not live.
- If VOD (past broadcast) storage is not enabled for the stream.
- For premieres (live, first-viewing events that combine uploaded videos with live chat).
- For reruns (subsequent (not live) streaming of any past broadcast, including past premieres).
Authentication
- OAuth token required
- Required scope:
channel:manage:broadcast
URL
POST https://api.twitch.tv/helix/streams/markers
Required Query Parameters
None
Optional Query Parameters
None
Required Body Parameter
| Name | Type | Parameter |
|---|---|---|
user_id | string | ID of the broadcaster in whose live stream the marker is created. |
Optional Body Parameter
| Name | Type | Parameter |
|---|---|---|
description | string | Description of or comments on the marker. Max length is 140 characters. |
Response Fields
| Field | Type | Description |
|---|---|---|
created_at | string | RFC3339 timestamp of the marker. |
description | string | Description of the marker. |
id | string | Unique ID of the marker. |
position_seconds | integer | Relative offset (in seconds) of the marker, from the beginning of the stream. |
Example Request
This creates a marker at the current location in user 123’s stream.
curl -X POST 'https://api.twitch.tv/helix/streams/markers' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{"user_id":"123", "description":"hello, this is a marker!"}'
Example Response
{
"data": [
{
"id": 123,
"created_at": "2018-08-20T20:10:03Z",
"description": "hello, this is a marker!",
"position_seconds": 244
}
]
}
Get Stream Markers
✎Gets a list of markers for either a specified user’s most recent stream or a specified VOD/video (stream), ordered by recency. A marker is an arbitrary point in a stream that the broadcaster wants to mark; e.g., to easily return to later. The only markers returned are those created by the user identified by the Bearer token.
The response has a JSON payload with a data field containing an array of marker information elements and a pagination field containing information required to query for more follow information.
Authentication
- OAuth token required
- Required scope:
user:read:broadcast
URL
GET https://api.twitch.tv/helix/streams/markers
Required Query Parameter
Only one of user_id and video_id must be specified.
| Name | Type | Description |
|---|---|---|
user_id | string | ID of the broadcaster from whose stream markers are returned. |
video_id | string | ID of the VOD/video whose stream markers are returned. |
Optional Query Parameters
| Name | Type | Description |
|---|---|---|
after | string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
before | string | Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
first | string | Number of values to be returned when getting videos by user or game ID. Limit: 100. Default: 20. |
Response Fields
| Field | Type | Description |
|---|---|---|
id | string | ID of the marker. |
created_at | string | RFC3339 timestamp of the marker. |
description | string | Description of the marker. |
pagination | object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. If this is empty, you are at the last page. |
position_seconds | integer | Relative offset (in seconds) of the marker, from the beginning of the stream. |
URL | string | A link to the stream with a query parameter that is a timestamp of the marker's location. |
user_id | string | ID of the user whose markers are returned. |
user_name | string | Display name corresponding to user_id. |
user_login | string | Login corresponding to user_id. |
video_id | string | ID of the stream (VOD/video) that was marked. |
Example Request
This returns the first 5 markers in the most recent stream of user 123.
curl -X GET 'https://api.twitch.tv/helix/streams/markers?user_id=123&first=5' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"user_id": "123",
"user_name": "TwitchName",
"user_login": "twitchname",
"videos": [
{
"video_id": "456",
"markers": [
{
"id": "106b8d6243a4f883d25ad75e6cdffdc4",
"created_at": "2018-08-20T20:10:03Z",
"description": "hello, this is a marker!",
"position_seconds": 244,
"URL": "https://twitch.tv/videos/456?t=0h4m06s"
},
...
]
}
]
}
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjoiMjk1MjA0Mzk3OjI1Mzpib29rbWFyazoxMDZiOGQ1Y"
}
}
Get Broadcaster Subscriptions
✎Description
Get all of the subscriptions for a specific broadcaster.
Authentication
- OAuth token required
- Required scope:
channel:read:subscriptions
Subscriptions can be requested on behalf of a broadcaster with a user access token or by a Twitch Extension with an app access token if the broadcaster has granted the channel:read:subscriptions scope from within the Twitch Extensions manager.
Pagination support
Forward only
URL
GET https://api.twitch.tv/helix/subscriptions
Required Query Parameter
| Parameter | Type | Description |
broadcaster_id |
string | User ID of the broadcaster. Must match the User ID in the Bearer token. |
Optional Query Parameter
| Parameter | Type | Description |
user_id |
string | Filters results to only include potential subscriptions made by the provided user IDs. Accepts up to 100 values. |
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without user_id. If a user_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query. |
first |
string | Maximum number of objects to return. Maximum: 100. Default: 20. |
Return Values
| Parameter | Type | Description |
broadcaster_id |
string | User ID of the broadcaster. |
broadcaster_login |
string | Login of the broadcaster. |
broadcaster_name |
string | Display name of the broadcaster. |
gifter_id |
string | If the subscription was gifted, this is the user ID of the gifter. Empty string otherwise. |
gifter_login |
string | If the subscription was gifted, this is the login of the gifter. Empty string otherwise. |
gifter_name |
string | If the subscription was gifted, this is the display name of the gifter. Empty string otherwise. |
is_gift |
Boolean | true if the subscription is a gift subscription. |
plan_name |
string | Name of the subscription. |
tier |
string | Type of subscription (Tier 1, Tier 2, Tier 3). 1000 = Tier 1, 2000 = Tier 2, 3000 = Tier 3 subscriptions. |
user_id |
string | ID of the subscribed user. |
user_name |
string | Display name of the subscribed user. |
user_login |
string | Login of the subscribed user. |
pagination |
object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. If this is empty, you are at the last page. |
total |
integer | The number of Twitch users subscribed to the broadcaster. |
Example Request
curl -X GET 'https://api.twitch.tv/helix/subscriptions?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"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
}
Check User Subscription
✎Checks if a specific user (user_id) is subscribed to a specific channel (broadcaster_id).
Authentication
- User access token with scope
user:read:subscriptions - App access token if the user has authorized your application with scope
user:read:subscriptions
URL
GET https://api.twitch.tv/helix/subscriptions/user
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | User ID of an Affiliate or Partner broadcaster. |
user_id |
string | User ID of a Twitch viewer. |
Response Fields
| Field | Type | Description |
|---|---|---|
broadcaster_id |
string | User ID of the broadcaster. |
broadcaster_login |
string | Login of the broadcaster. |
broadcaster_name |
string | Display name of the broadcaster. |
is_gift |
boolean | Indicates if the subscription is a gift. |
gifter_login |
string | Login of the gifter (if is_gift is true). |
gifter_name |
string | Display name of the gifter (if is_gift is true). |
tier |
string | Subscription tier. 1000 is tier 1, 2000 is tier 2, and 3000 is tier 3. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | User subscription returned successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
| 404 | User not subscribed to the channel. |
Example Request
Checks if the user TwitchDev (141981764) subscribes to the TwitchPresents (149747285) channel.
curl -X GET 'https://api.twitch.tv/helix/subscriptions/user?broadcaster_id=149747285&user_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response #1
If TwitchDev does subscribe to the TwitchPresents channel.
{
"data": [
{
"broadcaster_id": "149747285",
"broadcaster_name": "TwitchPresents",
"broadcaster_login": "twitchpresents",
"is_gift": false,
"tier": "1000"
}
]
}
Example Response #2
If TwitchDev does not subscribe to the TwitchPresents channel.
{
"error": "Not Found",
"message": "twitchdev has no subscription to twitchpresents",
"status": 404
}
Get All Stream Tags
✎Gets the list of all stream tags defined by Twitch, optionally filtered by tag ID(s).
The response has a JSON payload with a data field containing an array of tag elements and a pagination field containing information required to query for more tags.
Authentication
App access token
URL
GET https://api.twitch.tv/helix/tags/streams
Required Query Parameters
None
Optional Query Parameters
| Name | Type | Description |
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
first |
integer | Maximum number of objects to return. Maximum: 100. Default: 20. |
tag_id |
string | ID of a tag. Multiple IDs can be specified, separated by ampersands. If provided, only the specified tag(s) is(are) returned. Maximum of 100. |
Response Fields
| Field | Type | Description |
tag_id |
string | ID of the tag. |
is_auto |
Boolean | true if the tag is auto-generated; otherwise, false . An auto-generated tag is one automatically applied by Twitch (e.g., a language tag based on the broadcaster’s settings); these tags cannot be added or removed by the user. |
localization_names |
map[string]string | All localized names of the tag. |
localization_descriptions |
map[string]string | All localized descriptions of the tag. |
pagination |
object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. Not supported when tag_id is provided. |
Example Request
This gets the first page of stream tags defined by Twitch.
curl -X GET 'https://api.twitch.tv/helix/tags/streams' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"tag_id": "621fb5bf-5498-4d8f-b4ac-db4d40d401bf",
"is_auto": false,
"localization_names": {
"bg-bg": "Изчистване на 1 кредит",
"cs-cz": "1 čistý kredit",
"da-dk": "1 credit klaret",
"de-de": "Mit 1 Leben abschließen",
"el-gr": "1 μόνο πίστωση",
"en-us": "1 Credit Clear",
...
},
"localization_descriptions": {
"bg-bg": "За потоци с акцент върху завършване на аркадна игра с монети, в която не се използва продължаване",
"cs-cz": "Pro vysílání s důrazem na plnění mincových arkádových her bez použití pokračování.",
"da-dk": "Til streams med vægt på at gennemføre et arkadespil uden at bruge continues",
"de-de": "Für Streams mit dem Ziel, ein Coin-op-Arcade-Game mit nur einem Leben abzuschließen.",
"el-gr": "Για μεταδόσεις με έμφαση στην ολοκλήρωση παλαιού τύπου ηλεκτρονικών παιχνιδιών που λειτουργούν με κέρμα, χωρίς να χρησιμοποιούν συνέχειες",
"en-us": "For streams with an emphasis on completing a coin-op arcade game without using any continues",
...
}
},
...
],
"pagination": {
"cursor": "eyJiI..."
}
}
Get Stream Tags
✎Gets the list of current stream tags that have been set for a channel.
Authentication
OAuth Token required.
URL
GET https://api.twitch.tv/helix/streams/tags
Required Query Parameters
| Name | Type | Description |
broadcaster_id |
string | User ID of the channel to get tags. |
Optional Query Parameters
None
Response Fields
| Field | Type | Description |
tag_id |
string | ID of the tag. |
is_auto |
Boolean | true if the tag is auto-generated; otherwise, false . An auto-generated tag is one automatically applied by Twitch (e.g., a language tag based on the broadcaster’s settings); tags these cannot be added or removed by the user. |
localization_names |
map[string]string | All localized names of the tag. |
localization_descriptions |
map[string]string | All localized descriptions of the tag. |
Example Request
This gets the tags for the TwitchGaming channel.
curl -X GET 'https://api.twitch.tv/helix/streams/tags?broadcaster_id=527115020' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"tag_id": "6ea6bca4-4712-4ab9-a906-e3336a9d8039",
"is_auto": true,
"localization_names": {
"bg-bg": "английски",
"cs-cz": "Angličtina",
"da-dk": "Engelsk",
"de-de": "Englisch",
"el-gr": "Αγγλικά",
"en-us": "English",
...
},
"localization_descriptions": {
"bg-bg": "За потоци с използване на английски",
"cs-cz": "Pro vysílání obsahující angličtinu.",
"da-dk": "Til streams, hvori der indgår engelsk",
"de-de": "Für Streams auf Englisch.",
"el-gr": "Για μεταδόσεις που περιλαμβάνουν τη χρήση Αγγλικών",
"en-us": "For streams featuring the use of English",
...
}
}
]
}
Replace Stream Tags
✎Applies specified tags to a specified stream, overwriting any existing tags applied to that stream. If no tags are specified, all tags previously applied to the stream are removed. Automated tags are not affected by this operation.
Tags expire 72 hours after they are applied, unless the stream is live within that time period. If the stream is live within the 72-hour window, the 72-hour clock restarts when the stream goes offline. The expiration period is subject to change.
Authentication
- OAuth token required
- Required scope:
channel:manage:broadcast
URL
PUT https://api.twitch.tv/helix/streams/tags
Required Query Parameters
| Name | Type | Description |
broadcaster_id |
string | ID of the stream for which tags are to be replaced. |
Optional Query Parameters
None
Optional Body Parameter
Up to five tags can be applied to a stream. If no tag_ids is provided, all tags are removed from the stream.
| Name | Type | Description |
tag_ids |
string [] | IDs of tags to be applied to the stream. |
Example Request
This adds tags to broadcaster 257788195’s stream.
curl -X PUT 'https://api.twitch.tv/helix/streams/tags?broadcaster_id=257788195' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{"tag_ids":["621fb5bf-5498-4d8f-b4ac-db4d40d401bf","79977fb9-f106-4a87-a386-f1b0f99783dd"]}'
Example Response
204 No Content
Get Channel Teams
✎Retrieves a list of Twitch Teams of which the specified channel/broadcaster is a member.
Authentication
- User OAuth Token or App Access Token
URL
GET https://api.twitch.tv/helix/teams/channel
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | User ID for a Twitch user. |
Response Fields
| Field | Type | Description |
|---|---|---|
broadcaster_id |
string | User ID of the broadcaster. |
broadcaster_login |
string | Login of the broadcaster. |
broadcaster_name |
string | Display name of the broadcaster. |
background_image_url |
string | URL for the Team background image. |
banner |
string | URL for the Team banner. |
created_at |
string | Date and time the Team was created. |
updated_at |
string | Date and time the Team was last updated. |
info |
string | Team description. |
thumbnail_url |
string | Image URL for the Team logo. |
team_name |
string | Team name. |
team_display_name |
string | Team display name. |
id |
string | Team ID. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | List of Channel Teams returned successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
Retrieves a list of Twitch Teams that the broadcaster CSharpFritz belongs to.
curl -X GET 'https://api.twitch.tv/helix/teams/channel?broadcaster_id=96909659' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response
{
"data": [
{
"broadcaster_id": "96909659",
"broadcaster_name": "CSharpFritz",
"broadcaster_login": "csharpfritz",
"background_image_url": null,
"banner": null,
"created_at": "2019-02-11T12:09:22Z",
"updated_at": "2020-11-18T15:56:41Z",
"info": "<p>An outgoing and enthusiastic group of friendly channels that write code, teach about technology, and promote the technical community.</p>",
"thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/team-livecoders-team_logo_image-bf1d9a87ca81432687de60e24ad9593d-600x600.png",
"team_name": "livecoders",
"team_display_name": "Live Coders",
"id": "6358"
}
]
}
Get Teams
✎Gets information for a specific Twitch Team.
Authentication
- User OAuth Token or App Access Token
URL
GET https://api.twitch.tv/helix/teams
Required Query Parameters
One of the two optional query parameters must be specified to return Team information.
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
name |
string | Team name. |
id |
string | Team ID. |
Response Fields
| Field | Type | Description |
|---|---|---|
users |
Array of user objects | Users in the specified Team. |
users.user_id |
string | User ID of a Team member. |
users.user_login |
string | Login of a Team member. |
users.user_name |
string | Display name of a Team member. |
background_image_url |
string | URL of the Team background image. |
banner |
string | URL for the Team banner. |
created_at |
string | Date and time the Team was created. |
updated_at |
string | Date and time the Team was last updated. |
info |
string | Team description. |
thumbnail_url |
string | Image URL for the Team logo. |
team_name |
string | Team name. |
team_display_name |
string | Team display name. |
id |
string | Team ID. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | Team information returned successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
This example gets Team information for the Live Coders Team.
curl -X GET 'https://api.twitch.tv/helix/teams?id=6358' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response
{
"data": [
{
"users": [
{
"user_id": "278217731",
"user_name": "mastermndio",
"user_login": "mastermndio"
},
{
"user_id": "41284990",
"user_name": "jenninexus",
"user_login": "jenninexus"
},
...
],
"background_image_url": null,
"banner": null,
"created_at": "2019-02-11T12:09:22Z",
"updated_at": "2020-11-18T15:56:41Z",
"info": "<p>An outgoing and enthusiastic group of friendly channels that write code, teach about technology, and promote the technical community.</p>",
"thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/team-livecoders-team_logo_image-bf1d9a87ca81432687de60e24ad9593d-600x600.png",
"team_name": "livecoders",
"team_display_name": "Live Coders",
"id": "6358"
}
]
}
Get Users
✎Gets information about one or more specified Twitch users. Users are identified by optional user IDs and/or login name. If neither a user ID nor a login name is specified, the user is looked up by Bearer token.
The response has a JSON payload with a data field containing an array of user-information elements.
Authentication
- OAuth or App Access Token required.
Authorization
- OAuth token with
user:read:emailscope required to include the user’s verified email address in response.
URL
GET https://api.twitch.tv/helix/users
Required Query Parameters
None
Optional Query Parameters
| Name | Type | Description |
|---|---|---|
id |
string | User ID. Multiple user IDs can be specified. Limit: 100. |
login |
string | User login name. Multiple login names can be specified. Limit: 100. |
Note: The limit of 100 IDs and login names is the total limit. You can request, for example, 50 of each or 100 of one of them. You cannot request 100 of both.
A request can include a mixture of login names and user ID. If specifying multiple values (any combination of id and/or login values), separate them with ampersands; e.g.,GET https://api.twitch.tv/helix/users?login=<login name>&id=<user ID>...GET https://api.twitch.tv/helix/users?id=<user ID>&id=<user ID>...
GET https://api.twitch.tv/helix/users?login=<login name>&login=<login name>...
Response Fields
| Field | Type | Description |
|---|---|---|
broadcaster_type |
string | User’s broadcaster type: "partner", "affiliate", or "". |
description |
string | User’s channel description. |
display_name |
string | User’s display name. |
id |
string | User’s ID. |
login |
string | User’s login name. |
offline_image_url |
string | URL of the user’s offline image. |
profile_image_url |
string | URL of the user’s profile image. |
type |
string | User’s type: "staff", "admin", "global_mod", or "". |
view_count |
integer | Total number of views of the user’s channel. |
email |
string | User’s verified email address. Returned if the request includes the user:read:email scope. |
created_at |
string | Date when the user was created. |
Example Request
This gets information about user 141981764.
curl -X GET 'https://api.twitch.tv/helix/users?id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "141981764",
"login": "twitchdev",
"display_name": "TwitchDev",
"type": "",
"broadcaster_type": "partner",
"description": "Supporting third-party developers building Twitch integrations from chatbots to game integrations.",
"profile_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/8a6381c7-d0c0-4576-b179-38bd5ce1d6af-profile_image-300x300.png",
"offline_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/3f13ab61-ec78-4fe6-8481-8682cb3b0ac2-channel_offline_image-1920x1080.png",
"view_count": 5980557,
"email": "not-real@email.com",
"created_at": "2016-12-14T20:32:28.894263Z"
}
]
}
Update User
✎Updates the description of a user specified by the bearer token. Note that the description parameter is optional should other updatable parameters become available in the future. If the description parameter is not provided, no update will occur and the current user data is returned.
Authentication
-
OAuth token required
-
Required scope:
user:edit
URL
PUT https://api.twitch.tv/helix/users?description=<description>
Required Query Parameters
None
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
| description | string | User’s account description |
Response Fields
Response fields are the same as for Get Users. Email is only returned if the user:read:email is also provided.
Example Request
This updates the description of the user specified by Bearer token cfabdegwdoklmawdzdo98xt2fo512y.
curl -X PUT 'https://api.twitch.tv/helix/users?description=BaldAngel' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data":[{
"id": "44322889",
"login": "dallas",
"display_name": "dallas",
"type": "staff",
"broadcaster_type": "affiliate",
"description": "BaldAngel",
"profile_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/4d1f36cbf1f0072d-profile_image-300x300.png",
"offline_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-channel_offline_image-2e82c1df2a464df7-1920x1080.jpeg",
"view_count": 6995,
"email": "not-real@email.com",
"created_at": "2013-06-03T19:12:02.580593Z"
}]
}
Get Users Follows
✎Gets information on follow relationships between two Twitch users. This can return information like “who is qotrok following,” “who is following qotrok,” or “is user X following user Y.” Information returned is sorted in order, most recent follow first.
The response has a JSON payload with a data field containing an array of follow relationship elements and a pagination field containing information required to query for more follow information.
Authentication
- User OAuth Token or App Access Token
URLs
GET https://api.twitch.tv/helix/users/follows?from_id=<user ID>GET https://api.twitch.tv/helix/users/follows?to_id=<user ID>
At minimum, from_id or to_id must be provided for a query to be valid.
Required Query Parameters
None
Optional Query Paramaters
| Name | Type | Description |
|---|---|---|
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
first |
integer | Maximum number of objects to return. Maximum: 100. Default: 20. |
from_id |
string | User ID. The request returns information about users who are being followed by the from_id user. |
to_id |
string | User ID. The request returns information about users who are following the to_id user. |
Response Fields
| Field | Type | Description |
|---|---|---|
followed_at | string | Date and time when the from_id user followed the to_id user. |
from_id | string | ID of the user following the to_id user. |
from_login | string | Login of the user following the to_id user. |
from_name | string | Display name corresponding to from_id. |
pagination | object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. |
to_id | string | ID of the user being followed by the from_id user. |
to_login | string | Login of the user being followed by the from_id user. |
to_name | string | Display name corresponding to to_id. |
total | int | Total number of items returned.
|
Example Request
This gets the first 20 IDs of users who are following user 23161357.
curl -X GET 'https://api.twitch.tv/helix/users/follows?to_id=23161357' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"total": 12345,
"data":
[
{
"from_id": "171003792",
"from_login": "iiisutha067iii",
"from_name": "IIIsutha067III",
"to_id": "23161357",
"to_name": "LIRIK",
"followed_at": "2017-08-22T22:55:24Z"
},
{
"from_id": "113627897",
"from_login": "birdman616",
"from_name": "Birdman616",
"to_id": "23161357",
"to_name": "LIRIK",
"followed_at": "2017-08-22T22:55:04Z"
},
...
],
"pagination":{
"cursor": "eyJiIjpudWxsLCJhIjoiMTUwMzQ0MTc3NjQyNDQyMjAwMCJ9"
}
}
Create User Follows
✎Adds a specified user to the followers of a specified channel.
Authentication
- OAuth Token required
- Required scope:
user:edit:follows
URL
POST https://api.twitch.tv/helix/users/follows
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
from_id |
string | User ID of the follower |
to_id |
string | ID of the channel to be followed by the user |
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
allow_notifications |
Boolean | If true, the user gets email or push notifications (depending on the user’s notification settings) when the channel goes live. Default value is false. |
Response Codes
| Code | Meaning |
|---|---|
| 204 | Successfully created follows |
| 400 | Missing Query Parameter |
| 422 | Entity cannot be processed |
Example Request
This example creates a user follow.
curl -X POST 'https://api.twitch.tv/helix/users/follows' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
--data-raw '{"to_id": "41245072","from_id": "57059344"}'
Example Response
204 No Content
Delete User Follows
✎Deletes a specified user from the followers of a specified channel.
Authentication
-
OAuth Token required
-
Required scope:
user:edit:follows
URL
DELETE https://api.twitch.tv/helix/users/follows
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
from_id |
string | User ID of the follower |
to_id |
string | Channel to be unfollowed by the user |
Optional Query Parameters
None
Response Codes
| Code | Meaning |
|---|---|
| 204 | User successfully deleted from list of channel followers |
| 400 | Missing Query Parameter |
| 422 | Entity cannot be processed |
Example Request
This request deletes a user from the followers of a channel.
curl -X DELETE 'https://api.twitch.tv/helix/users/follows?from_id=57059344&to_id=41245072' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'
Example Response
204 No Content
Get User Block List
✎Gets a specified user’s block list. The list is sorted by when the block occurred in descending order (i.e. most recent block first).
Authentication
- OAuth user token required
- Required scope:
user:read:blocked_users
URL
GET https://api.twitch.tv/helix/users/blocks
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
broadcaster_id |
string | User ID for a Twitch user. |
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
first |
integer | Maximum number of objects to return. Maximum: 100. Default: 20. |
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
Response Fields
| Field | Type | Description |
|---|---|---|
user_id |
string | User ID of the blocked user. |
user_login |
string | Login of the blocked user. |
display_name |
string | Display name of the blocked user. |
Response Codes
| Code | Meaning |
|---|---|
| 200 | User’s block list returned successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
This example gets a list of users blocked by the specified user.
curl -X GET 'https://api.twitch.tv/helix/users/blocks?broadcaster_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
Example Response
{
"data": [
{
"user_id": "135093069",
"user_login": "bluelava",
"display_name": "BlueLava"
},
{
"user_id": "27419011",
"user_login": "travistyoj",
"display_name": "TravistyOJ"
}
]
}
Block User
✎Blocks the specified user on behalf of the authenticated user.
Authentication
- OAuth user token required
- Required scope:
user:manage:blocked_users
URL
PUT https://api.twitch.tv/helix/users/blocks
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
target_user_id |
string | User ID of the user to be blocked. |
Optional Query Parameters
| Parameter | Type | Description |
|---|---|---|
source_context |
string | Source context for blocking the user. Valid values: "chat", "whisper". |
reason |
string | Reason for blocking the user. Valid values: "spam", "harassment", or "other". |
Response Codes
| Code | Meaning |
|---|---|
| 204 | User blocked successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
This example blocks a user with an ID of 198704263 on behalf of the authenticated user.
curl -X PUT 'https://api.twitch.tv/helix/users/blocks?target_user_id=198704263' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
Example Response
204 No Content
Unblock User
✎Unblocks the specified user on behalf of the authenticated user.
Authentication
- OAuth user token required
- Required scope:
user:manage:blocked_users
URL
DELETE https://api.twitch.tv/helix/users/blocks
Required Query Parameters
| Parameter | Type | Description |
|---|---|---|
target_user_id |
string | User ID of the user to be unblocked. |
Optional Query Parameters
None.
Response Codes
| Code | Meaning |
|---|---|
| 204 | User unblocked successfully. |
| 400 | Request was invalid. |
| 401 | Authorization failed. |
Example Request
This example unblocks a user with an ID of 198704263 on behalf of the authenticated user.
curl -X DELETE 'https://api.twitch.tv/helix/users/blocks?target_user_id=198704263' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
Example Response
204 No Content
Get User Extensions
✎Gets a list of all extensions (both active and inactive) for a specified user, identified by a Bearer token.
The response has a JSON payload with a data field containing an array of user-information elements.
Authentication
- OAuth token required
- Required scope:
user:read:broadcast
URL
GET https://api.twitch.tv/helix/users/extensions/list
Required Query Parameters
None
Optional Query Parameters
None
Response Fields
| Field | Type | Description |
|---|---|---|
can_activate | boolean | Indicates whether the extension is configured such that it can be activated. |
id | string | ID of the extension. |
name | string | Name of the extension. |
type | string array | Types for which the extension can be activated. Valid values: "component", "mobile", "panel", "overlay". |
version | string | Version of the extension. |
Example Request
This gets installed extensions for the user identified by Bearer token cfabdegwdoklmawdzdo98xt2fo512y.
curl -X GET 'https://api.twitch.tv/helix/users/extensions/list' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "wi08ebtatdc7oj83wtl9uxwz807l8b",
"version": "1.1.8",
"name": "Streamlabs Leaderboard",
"can_activate": true,
"type": [
"panel"
]
},
{
"id": "d4uvtfdr04uq6raoenvj7m86gdk16v",
"version": "2.0.2",
"name": "Prime Subscription and Loot Reminder",
"can_activate": true,
"type": [
"overlay"
]
},
{
"id": "rh6jq1q334hqc2rr1qlzqbvwlfl3x0",
"version": "1.1.0",
"name": "TopClip",
"can_activate": true,
"type": [
"mobile",
"panel"
]
},
{
"id": "zfh2irvx2jb4s60f02jq0ajm8vwgka",
"version": "1.0.19",
"name": "Streamlabs",
"can_activate": true,
"type": [
"mobile",
"overlay"
]
},
{
"id": "lqnf3zxk0rv0g7gq92mtmnirjz2cjj",
"version": "0.0.1",
"name": "Dev Experience Test",
"can_activate": true,
"type": [
"component",
"mobile",
"panel",
"overlay"
]
}
]
}
Get User Active Extensions
✎Gets information about active extensions installed by a specified user, identified by a user ID or Bearer token.
Authentication
- OAuth token required
- Optional scope:
user:read:broadcastoruser:edit:broadcast
URL
GET https://api.twitch.tv/helix/users/extensions
Required Query Parameters
None
Optional Query Parameter
| Name | Type | Description |
|---|---|---|
user_id | string | ID of the user whose installed extensions will be returned. Limit: 1. |
Response Fields
| Field | Type | Description |
|---|---|---|
active | boolean | Activation state of the extension, for each extension type (component, overlay, mobile, panel). If false, no other data is provided. |
component | map | Contains data for video-component Extensions. |
id | string | ID of the extension. |
name | string | Name of the extension. |
overlay | map | Contains data for video-overlay Extensions. |
panel | map | Contains data for panel Extensions. |
version | string | Version of the extension. |
x | int | (Video-component Extensions only) X-coordinate of the placement of the extension. |
y | int | (Video-component Extensions only) Y-coordinate of the placement of the extension. |
Example Request
This updates the description of the user specified by Bearer token cfabdegwdoklmawdzdo98xt2fo512y.
curl -X GET 'https://api.twitch.tv/helix/users/extensions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": {
"panel": {
"1": {
"active": true,
"id": "rh6jq1q334hqc2rr1qlzqbvwlfl3x0",
"version": "1.1.0",
"name": "TopClip"
},
"2": {
"active": true,
"id": "wi08ebtatdc7oj83wtl9uxwz807l8b",
"version": "1.1.8",
"name": "Streamlabs Leaderboard"
},
"3": {
"active": true,
"id": "naty2zwfp7vecaivuve8ef1hohh6bo",
"version": "1.0.9",
"name": "Streamlabs Stream Schedule & Countdown"
}
},
"overlay": {
"1": {
"active": true,
"id": "zfh2irvx2jb4s60f02jq0ajm8vwgka",
"version": "1.0.19",
"name": "Streamlabs"
}
},
"component": {
"1": {
"active": true,
"id": "lqnf3zxk0rv0g7gq92mtmnirjz2cjj",
"version": "0.0.1",
"name": "Dev Experience Test",
"x": 0,
"y": 0
},
"2": {
"active": false
}
}
}
}
Update User Extensions
✎Updates the activation state, extension ID, and/or version number of installed extensions for a specified user, identified by a Bearer token. If you try to activate a given extension under multiple extension types, the last write wins (and there is no guarantee of write order).
Authentication
- OAuth token required
- Required scope:
user:edit:broadcast
URL
PUT https://api.twitch.tv/helix/users/extensions
Required Query Parameters
None
Optional Query Parameters
None
Response Fields
Response fields are the same as for Get User Active Extensions.
Example Request
This updates the installed extensions of the user specified by Bearer token cfabdegwdoklmawdzdo98xt2fo512y.
curl -X PUT 'https://api.twitch.tv/helix/users/extensions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H "Content-Type: application/json" \
-d '{
"data": {
"panel": {
"1": {
"active": true,
"id": "rh6jq1q334hqc2rr1qlzqbvwlfl3x0",
"version": "1.1.0"
},
"2": {
"active": true,
"id": "wi08ebtatdc7oj83wtl9uxwz807l8b",
"version": "1.1.8"
},
"3": {
"active": true,
"id": "naty2zwfp7vecaivuve8ef1hohh6bo",
"version": "1.0.9"
}
},
"overlay": {
"1": {
"active": true,
"id": "zfh2irvx2jb4s60f02jq0ajm8vwgka",
"version": "1.0.19"
}
},
"component": {
"1": {
"active": true,
"id": "lqnf3zxk0rv0g7gq92mtmnirjz2cjj",
"version": "0.0.1",
"x": 0,
"y": 0
},
"2": {
"active": false
}
}
}
}'
Example Response
{
"data": {
"panel": {
"1": {
"active": true,
"id": "rh6jq1q334hqc2rr1qlzqbvwlfl3x0",
"version": "1.1.0",
"name": "TopClip"
},
"2": {
"active": true,
"id": "wi08ebtatdc7oj83wtl9uxwz807l8b",
"version": "1.1.8",
"name": "Streamlabs Leaderboard"
},
"3": {
"active": true,
"id": "naty2zwfp7vecaivuve8ef1hohh6bo",
"version": "1.0.9",
"name": "Streamlabs Stream Schedule & Countdown"
}
},
"overlay": {
"1": {
"active": true,
"id": "zfh2irvx2jb4s60f02jq0ajm8vwgka",
"version": "1.0.19",
"name": "Streamlabs"
}
},
"component": {
"1": {
"active": true,
"id": "lqnf3zxk0rv0g7gq92mtmnirjz2cjj",
"version": "0.0.1",
"name": "Dev Experience Test",
"x": 0,
"y": 0
},
"2": {
"active": false
}
}
}
}
Get Videos
✎Gets video information by one or more video IDs, user ID, or game ID. For lookup by user or game, several filters are available that can be specified as query parameters.
Authentication
- User OAuth Token or App Access Token
Pagination Support
Forward pagination for requests that specify user_id or game_id. If a game is specified, a maximum of 500 results are available.
URL
GET https://api.twitch.tv/helix/videos
Required Query Parameters
Each request must specify one or more video ids, one user_id, or one game_id.
| Name | Type | Description |
|---|---|---|
id |
string | ID of the video being queried. Limit: 100. If this is specified, you cannot use any of the optional query parameters below. |
user_id |
string | ID of the user who owns the video. Limit 1. |
game_id |
string | ID of the game the video is of. Limit 1. |
Optional Query Parameters
These can be used if the request specifies a user_id or game_id, not a video id.
| Name | Type | Description |
|---|---|---|
after |
string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
before |
string | Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
first |
string | Number of values to be returned when getting videos by user or game ID. Limit: 100. Default: 20. |
language |
string | Language of the video being queried. Limit: 1. A language value must be either the ISO 639-1 two-letter code for a supported stream language or “other”. |
period |
string | Period during which the video was created. Valid values: "all", "day", "week", "month". Default: "all". |
sort |
string | Sort order of the videos. Valid values: "time", "trending", "views". Default: "time". |
type |
string | Type of video. Valid values: "all", "upload", "archive", "highlight". Default: "all". |
Response Fields
| Fields | Type | Description |
|---|---|---|
id |
string | ID of the video. |
stream_id |
string | ID of the stream that the video originated from if the type is "archive". Otherwise set to null. |
user_id |
string | ID of the user who owns the video. |
user_login |
string | Login of the user who owns the video. |
user_name |
string | Display name corresponding to user_id. |
title |
string | Title of the video. |
description |
string | Description of the video. |
created_at |
string | Date when the video was created. |
published_at |
string | Date when the video was published. |
url |
object | URL of the video. |
thumbnail_url |
object | Template URL for the thumbnail of the video. |
viewable |
string | Indicates whether the video is publicly viewable. Valid values: "public", "private". |
view_count |
int | Number of times the video has been viewed. |
language |
string | Language of the video. A language value is either the ISO 639-1 two-letter code for a supported stream language or “other”. |
type |
string | Type of video. Valid values: "upload", "archive", "highlight". |
duration |
string | Length of the video. |
muted_segments |
object[] | Array of muted segments in the video. If there are no muted segments, the value will be null. |
segment.duration |
integer | Duration of the muted segment. |
segment.offset |
integer | Offset in the video at which the muted segment begins. |
pagination |
object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. |
Example Request
This gets information about the video with ID 335921245.
curl -X GET 'https://api.twitch.tv/helix/videos?id=335921245' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
{
"id": "335921245",
"stream_id": null,
"user_id": "141981764",
"user_login": "twitchdev",
"user_name": "TwitchDev",
"title": "Twitch Developers 101",
"description": "Welcome to Twitch development! Here is a quick overview of our products and information to help you get started.",
"created_at": "2018-11-14T21:30:18Z",
"published_at": "2018-11-14T22:04:30Z",
"url": "https://www.twitch.tv/videos/335921245",
"thumbnail_url": "https://static-cdn.jtvnw.net/cf_vods/d2nvs31859zcd8/twitchdev/335921245/ce0f3a7f-57a3-4152-bc06-0c6610189fb3/thumb/index-0000000000-%{width}x%{height}.jpg",
"viewable": "public",
"view_count": 1863062,
"language": "en",
"type": "upload",
"duration": "3m21s",
"muted_segments": [
{
"duration": 30,
"offset": 120
}
]
}
],
"pagination": {}
}
Delete Videos
✎Deletes one or more videos. Videos are past broadcasts, Highlights, or uploads.
Invalid Video IDs will be ignored (i.e. IDs provided that do not have a video associated with it). If the OAuth user token does not have permission to delete even one of the valid Video IDs, no videos will be deleted and the response will return a 401.
Authentication
- User OAuth token
- Required scope:
channel:manage:videos
URL
DELETE https://api.twitch.tv/helix/videos
Required Query Parameters
| Name | Type | Description |
|---|---|---|
id |
string | ID of the video(s) to be deleted. Limit: 5. |
Optional Query Parameters
None.
Response Codes
| Code | Meaning |
|---|---|
| 200 | Video(s) deleted. |
| 400 | Request was invalid. |
| 401 | Authorization failed; either for the API request itself or if the requester is not authorized to delete the specified videos. |
Example Request
This example deletes two videos with the IDs 1234 and 9876.
curl -X DELETE 'https://api.twitch.tv/helix/videos?id=1234&id=9876' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"data": [
"1234",
"9876"
]
}
Get Webhook Subscriptions
✎Gets the Webhook subscriptions of an application identified by a Bearer token, in order of expiration.
The response has a JSON payload with a data field containing an array of subscription elements and a pagination field containing information required to query for more subscriptions.
Authentication
App access token
URL
GET https://api.twitch.tv/helix/webhooks/subscriptions
Required Query Parameters
None
Optional Query Parameters
| Name | Type | Description |
|---|---|---|
after | string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query. |
first | string | Number of values to be returned per page. Limit: 100. Default: 20. |
Response Fields
| Field | Type | Description |
|---|---|---|
callback | string | The callback provided for this subscription. |
expires_at | string | Date and time when this subscription expires. Encoded as RFC3339. The timezone is always UTC (“Z”). |
pagination | object containing a string | A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. If this is empty, you are at the last page. |
topic | string | The topic used in the initial subscription. |
total | int | A hint at the total number of results returned, on all pages. This is an approximation: as you page through the list, some subscriptions may expire and others may be added. |
Example Request
This gets up to 10 webhook subscriptions.
curl -X GET 'https://api.twitch.tv/helix/webhooks/subscriptions?first=10&after=eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IiJ9fQ' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'
Example Response
{
"total": 12,
"data": [
{
"topic": "https://api.twitch.tv/helix/streams?user_id=123",
"callback": "http://example.com/your_callback",
"expires_at": "2018-07-30T20:00:00Z"
},
{
"topic": "https://api.twitch.tv/helix/streams?user_id=345",
"callback": "http://example.com/your_callback",
"expires_at": "2018-07-30T20:03:00Z"
}
],
"pagination": {
"cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IkFYc2laU0k2TVN3aWFTSTZNWDAifX0"
}
}