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	Gets the list of Extension transactions for a given Extension. This 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 `client_id`.
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.
Charity	Get Charity Campaign	BETA Gets information about the broadcaster’s active charity campaign.
Chat	Get Channel Emotes	Gets all emotes that the specified Twitch channel created. For example, subscriber emotes, follower emotes, and Bits tier emotes.
Chat	Get Global Emotes	Gets all global emotes. Global emotes are Twitch-specific emoticons that every user can use in Twitch chat.
Chat	Get Emote Sets	Gets emotes for one or more specified emote sets.
Chat	Get Channel Chat Badges	Gets a list of custom chat badges that can be used in chat for the specified channel.
Chat	Get Global Chat Badges	Gets a list of chat badges that can be used in chat for any channel.
Chat	Get Chat Settings	Gets the broadcaster’s chat settings.
Chat	Update Chat Settings	Updates the broadcaster’s chat settings.
Chat	Send Chat Announcement	NEW Sends an announcement to the broadcaster’s chat room.
Chat	Get User Chat Color	NEW Gets the color used for the user’s name in chat.
Chat	Update User Chat Color	NEW Updates the color used for the user’s name in chat.
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	Update Drops Entitlements	Updates the fulfillment status on a set of Drops entitlements, specified by their entitlement IDs.
Entitlements	Redeem Code	Redeems one or more redemption codes.
Extensions	Get Extension Configuration Segment	Gets the specified configuration segment from the specified extension.
Extensions	Set Extension Configuration Segment	Sets a single configuration segment of any type. The segment type is specified as a body parameter.
Extensions	Set Extension Required Configuration	Enable activation of a specified Extension, after any required broadcaster configuration is correct.
Extensions	Send Extension PubSub Message	Forward a message using the same mechanism as the send JavaScript helper function.
Extensions	Get Extension Live Channels	Returns one page of live channels that have installed or activated a specific Extension.
Extensions	Get Extension Secrets	Retrieves a specified Extension’s secret data consisting of a version and an array of secret objects.
Extensions	Create Extension Secret	Creates a JWT signing secret for a specific Extension
Extensions	Send Extension Chat Message	Sends a specified chat message to a specified channel.
Extensions	Get Extensions	Gets information about your Extensions; either the current version or a specified version.
Extensions	Get Released Extensions	Gets information about a released Extension; either the current version or a specified version.
Extensions	Get Extension Bits Products	Gets a list of Bits products that belongs to an Extension.
Extensions	Update Extension Bits Product	Add or update a Bits products that belongs to an Extension.
EventSub	Create EventSub Subscription	Creates an EventSub subscription.
EventSub	Delete EventSub Subscription	Deletes an EventSub subscription.
EventSub	Get EventSub Subscriptions	Gets a list of your EventSub subscriptions. The list is paginated and ordered by the oldest subscription 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.
Goals	Get Creator Goals	Gets the broadcaster’s list of active goals.
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 AutoMod Settings	Gets the broadcaster’s AutoMod settings.
Moderation	Update AutoMod Settings	Updates the broadcaster’s AutoMod settings.
Moderation	Get Banned Users	Returns all banned and timed-out users for a channel.
Moderation	Ban User	Bans a user from participating in a broadcaster’s chat room, or puts them in a timeout.
Moderation	Unban User	Removes the ban or timeout that was placed on the specified user.
Moderation	Get Blocked Terms	Gets the broadcaster’s list of non-private, blocked words or phrases.
Moderation	Add Blocked Term	Adds a word or phrase to the broadcaster’s list of blocked terms.
Moderation	Remove Blocked Term	Removes the word or phrase that the broadcaster is blocking users from using in their chat room.
Moderation	Delete Chat Messages	NEW Removes a single chat message or all chat messages from the broadcaster’s chat room.
Moderation	Get Moderators	Returns all moderators in a channel.
Moderation	Add Channel Moderator	NEW Adds a moderator to the broadcaster’s chat room.
Moderation	Remove Channel Moderator	NEW Removes a moderator from the broadcaster’s chat room.
Moderation	Get VIPs	NEW Gets a list of the channel’s VIPs.
Moderation	Add Channel VIP	NEW Adds a VIP to the broadcaster’s chat room.
Moderation	Remove Channel VIP	NEW Removes a VIP from the broadcaster’s chat room.
Polls	Get Polls	Get information about all polls or specific polls for a Twitch channel. Poll information is available for 90 days.
Polls	Create Poll	Create a poll for a specific Twitch channel.
Polls	End Poll	End a poll that is currently active.
Predictions	Get Predictions	Get information about all Channel Points Predictions or specific Channel Points Predictions for a Twitch channel.
Predictions	Create Prediction	Create a Channel Points Prediction for a specific Twitch channel.
Predictions	End Prediction	Lock, resolve, or cancel a Channel Points Prediction.
Raids	Start a raid	NEW Raid another channel by sending the broadcaster’s viewers to the targeted channel.
Raids	Cancel a raid	NEW Cancel a pending raid.
Schedule	Get Channel Stream Schedule	Gets all scheduled broadcasts or specific scheduled broadcasts from a channel’s stream schedule.
Schedule	Get Channel iCalendar	Gets all scheduled broadcasts from a channel’s stream schedule as an iCalendar.
Schedule	Update Channel Stream Schedule	Update the settings for a channel’s stream schedule.
Schedule	Create Channel Stream Schedule Segment	Create a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule.
Schedule	Update Channel Stream Schedule Segment	Update a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule.
Schedule	Delete Channel Stream Schedule Segment	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.
Music	Get Soundtrack Current Track	BETA Gets the Soundtrack track that the broadcaster is playing.
Music	Get Soundtrack Playlist	BETA Gets the tracks of a Soundtrack playlist.
Music	Get Soundtrack Playlists	BETA Gets a list of Soundtrack playlists.
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 that Twitch defines. You can also filter the list by one or more tag IDs.
Tags	Get Stream Tags	Gets the list of stream tags that are set on the specified channel.
Tags	Replace Stream Tags	Applies one or more tags to the specified channel, overwriting any existing tags.
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	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.
Whispers	Send Whisper	NEW Sends a whisper message to the specified user.

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"`. `"day"` – 00:00:00 on the day specified in `started_at`, through 00:00:00 on the following day. `"week"` – 00:00:00 on Monday of the week specified in `started_at`, through 00:00:00 on the following Monday. `"month"` – 00:00:00 on the first day of the month specified in `started_at`, through 00:00:00 on the first day of the following month. `"year"` – 00:00:00 on the first day of the year specified in `started_at`, through 00:00:00 on the first day of the following year. `"all"` – The lifetime of the broadcaster's channel. If this is specified (or used by default), `started_at` is ignored.
`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

✎

Gets the list of Extension transactions for a given Extension. This 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

Authentication

App Access Token

Required Query Parameters

Parameter	Type	Description
`extension_id`	string	ID of the Extension to list transactions for. Maximum: 1

Optional Query Parameters

Parameter	Type	Description
`id`	string	Transaction IDs to look up. Can include multiple to fetch multiple transactions in a single request. For example, `/helix/extensions/transactions?extension_id=1234&id=1&id=2&id=3` Maximum: 100.
`after`	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`	integer	Maximum number of objects to return. Maximum: 100. Default: 20.

Return Values

Parameter	Type	Description
`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	Represents the product acquired, as it looked at the time of the transaction.
`product_data.domain`	string	Set to twitch.ext + your Extension ID.
`product_data.sku`	string	Unique identifier for the product across the Extension.
`product_data.cost`	object	Represents the cost to acquire the product.
`product_data.cost.amount`	integer	Number of Bits required to acquire the product.
`product_data.cost.type`	string	Identifies the contribution method. Currently only `bits`.
`product_data.inDevelopment`	boolean	Indicates if the product is in development.
`product_data.displayName`	string	Display name of the product.
`expiration`	string	Always empty since only unexpired products can be purchased.
`broadcast`	boolean	Indicates whether or not the data was sent over the Extension PubSub to all instances of the Extension.
`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.

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": {
        "domain": "twitch.ext.uo6dggojyb8d6soh92zknwmi5ej1q2",
        "sku": "testSku100",
        "cost": {
          "amount": 100,
          "type": "bits"
        },
        "inDevelopment": false,
        "displayName": "Test Product 100",
        "expiration": "",
        "broadcast": 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": {
        "domain": "twitch.ext.uo6dggojyb8d6soh92zknwmi5ej1q2",
        "sku": "testSku200",
        "cost": {
          "amount": 200,
          "type": "bits"
        },
        "inDevelopment": false,
        "displayName": "Test Product 200",
        "expiration": "",
        "broadcast": 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	The ID of the broadcaster whose channel you want to get. To specify more than one ID, include this parameter for each broadcaster you want to get. For example, `broadcaster_id=1234&broadcaster_id=5678`. You may specify a maximum of 100 IDs.

Optional Query Parameters

None

Return Values

Parameter	Type	Description
`broadcaster_id`	string	Twitch User ID of this channel owner.
`broadcaster_login`	string	Broadcaster’s user login name.
`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.

The maximum number of custom rewards per channel is 50, which includes both enabled and disabled rewards.

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. The title may contain a maximum of 45 characters and it must be unique amongst all of the broadcaster’s custom rewards.
`cost`	integer	The cost of the reward.

Optional Body Parameters

Parameter	Type	Description
`prompt`	string	The prompt for the viewer when redeeming the reward. The maximum length is 200 characters.
`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: A query parameter is missing or is invalid, or the request exceeds the maximum number of rewards that you may create.
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. The title may contain a maximum of 45 characters and it must be unique amongst all of the broadcaster’s custom rewards.
`prompt`	string	The prompt for the viewer when they are redeeming the reward. The prompt is limited to a maximum length is 200 characters.
`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 Charity Campaign

✎

BETA Gets information about the charity campaign that a broadcaster is running, such as their fundraising goal and the amount that’s been donated so far.

To receive events as donations occur, use the channel.charity_campaign.donate subscription type.

Authorization

Requires a user access token that includes the channel:read:charity scope. The ID in the broadcaster_id query parameter must match the user ID in the access token.

URL

GET https://api.twitch.tv/helix/charity/campaigns

Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that’s actively running a charity campaign.

Response Fields

Field	Type	Description
data	Object[]	A list that contains the charity campaign that the broadcaster is currently running. The array is empty if the broadcaster is not running a charity campaign; the campaign information is no longer available as soon as the campaign ends.
id	String	An ID that uniquely identifies the charity campaign.
broadcaster_id	String	An ID that uniquely identifies the broadcaster that’s running the campaign.
broadcaster_login	String	The broadcaster’s login name.
broadcaster_name	String	The broadcaster’s display name.
charity_name	String	The charity’s name.
charity_description	String	A description of the charity.
charity_logo	String	A URL to an image of the charity’s logo. The image’s type is PNG and its size is 100px X 100px.
charity_website	String	A URL to the charity’s website.
current_amount	Object	An object that contains the current amount of donations that the campaign has received.
value	Integer	The monetary amount. The amount is specified in the currency’s minor unit. For example, the minor units for USD is cents, so if the amount is $5.50 USD, `value` is set to 550.
decimal_places	Integer	The number of decimal places used by the currency. For example, USD uses two decimal places. Use this number to translate `value` from minor units to major units by using the formula: `value / 10^decimal_places`
currency	String	The ISO-4217 three-letter currency code that identifies the type of currency in `value`.
target_amount	Object	An object that contains the amount of money that the campaign is trying to raise. This field may be null if the broadcaster has not defined a target goal.
value	Integer	The monetary amount. The amount is specified in the currency’s minor unit. For example, the minor units for USD is cents, so if the amount is $5.50 USD, `value` is set to 550.
decimal_places	Integer	The number of decimal places used by the currency. For example, USD uses two decimal places. Use this number to translate `value` from minor units to major units by using the formula: `value / 10^decimal_places`
currency	String	The ISO-4217 three-letter currency code that identifies the type of currency in `value`.

Response Codes

Code	Description
200 OK	Successfully retrieved information about the broadcaster’s active charity campaign.
400 Bad Request	Possible reasons: The broadcaster_id query parameter is required. The broadcaster_id query parameter is not valid.
401 Unauthorized	Possible reasons: The ID in the broadcaster_id query parameter must match the user ID in the access token. The Authorization header is required and must contain a user access token. The user access token must include the channel:read:charity scope. The OAuth token is not valid. The client ID specified in the Client-Id header must match the client ID specified in the OAuth token.
403 Forbidden	The broadcaster must be a partner or affiliate.

Example Request

Gets the broadcaster’s active charity campaign.

curl -X GET 'https://api.twitch.tv/helix/charity/campaigns?broadcaster_id=123456' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'

Example Response

{
  "data": [
    {
      "id": "123-abc-456-def",
      "broadcaster_id": "123456",
      "broadcaster_name": "SunnySideUp",
      "broadcaster_login": "sunnysideup",
      "charity_name": "Example name",
      "charity_description": "Example description",
      "charity_logo": "https://example.url/logo.png",
      "charity_website": "https://www.example.com",
      "current_amount": {
        "value": 86000,
        "decimal_places": 2,
        "currency": "USD"
      },
      "target_amount": {
        "value": 1500000,
        "decimal_places": 2,
        "currency": "USD"
      }
    }
  ]
}

Get Channel Emotes

✎

Gets all emotes that the specified Twitch channel created. Broadcasters create these custom emotes for users who subscribe to or follow the channel, or cheer Bits in the channel’s chat window. For information about the custom emotes, see subscriber emotes, Bits tier emotes, and follower emotes.

NOTE: With the exception of custom follower emotes, users may use custom emotes in any Twitch chat.

Learn More

Authorization

Requires a user or application OAuth access token.

URL

GET https://api.twitch.tv/helix/chat/emotes

Required Query Parameter

Parameter	Type	Description
`broadcaster_id`	string	An ID that identifies the broadcaster to get the emotes from.

Response Fields

Parameter	Type	Description
`data`	object array	A list of emotes that the specified channel created.
`id`	string	An ID that identifies the emote.
`name`	string	The name of the emote. This is the name that viewers type in the chat window to get the emote to appear.
`images`	object	Contains the image URLs for the emote. These image URLs will always provide a static (i.e., non-animated) emote image with a light background. NOTE: The preference is for you to use the templated URL in the `template` field to fetch the image instead of using these URLs.
`url_1x`	string	A URL to the small version (28px x 28px) of the emote.
`url_2x`	string	A URL to the medium version (56px x 56px) of the emote.
`url_4x`	string	A URL to the large version (112px x 112px) of the emote.
`tier`	string	The subscriber tier at which the emote is unlocked. This field contains the tier information only if `emote_type` is set to `subscriptions`, otherwise, it’s an empty string.
`emote_type`	string	The type of emote. The possible values are: bitstier — Indicates a custom Bits tier emote. follower — Indicates a custom follower emote. subscriptions — Indicates a custom subscriber emote.
`emote_set_id`	string	An ID that identifies the emote set that the emote belongs to.
`format`	string array	The formats that the emote is available in. For example, if the emote is available only as a static PNG, the array contains only `static`. But if it’s available as a static PNG and an animated GIF, the array contains `static` and `animated`. The possible formats are: animated — Indicates an animated GIF is available for this emote. static — Indicates a static PNG file is available for this emote.
`scale`	string array	The sizes that the emote is available in. For example, if the emote is available in small and medium sizes, the array contains 1.0 and 2.0. Possible sizes are: 1.0 — A small version (28px x 28px) is available. 2.0 — A medium version (56px x 56px) is available. 3.0 — A large version (112px x 112px) is available.
`theme_mode`	string array	The background themes that the emote is available in. Possible themes are: dark light
`template`	string	A templated URL. Use the values from `id`, `format`, `scale`, and `theme_mode` to replace the like-named placeholder strings in the templated URL to create a CDN (content delivery network) URL that you use to fetch the emote. For information about what the template looks like and how to use it to fetch emotes, see Emote CDN URL format.

Response Codes

Code	Meaning
200	Successfully returned the custom emotes for the specified broadcaster.
400	The request was invalid.
401	The caller failed authentication. Verify that your access token and client ID are valid.

Example Request

This example returns custom emotes defined in the TwitchDev channel.

curl -X GET 'https://api.twitch.tv/helix/chat/emotes?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

# Twitch CLI example that gets the custom emotes for the specified channel.

twitch api get /chat/emotes -q broadcaster_id=141981764

Example Response

{
  "data": [
    {
      "id": "304456832",
      "name": "twitchdevPitchfork",
      "images": {
        "url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/1.0",
        "url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/2.0",
        "url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/3.0"
      },
      "tier": "1000",
      "emote_type": "subscriptions",
      "emote_set_id": "301590448",
      "format": [
        "static"
      ],
      "scale": [
        "1.0",
        "2.0",
        "3.0"
      ],
      "theme_mode": [
        "light",
        "dark"
      ]
    },
    ...
    {
      "id": "emotesv2_4c3b4ed516de493bbcd2df2f5d450f49",
      "name": "twitchdevHyperPitchfork",
      "images": {
        "url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_4c3b4ed516de493bbcd2df2f5d450f49/static/light/1.0",
        "url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_4c3b4ed516de493bbcd2df2f5d450f49/static/light/2.0",
        "url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/emotesv2_4c3b4ed516de493bbcd2df2f5d450f49/static/light/3.0"
      },
      "tier": "1000",
      "emote_type": "subscriptions",
      "emote_set_id": "318939165",
      "format": [
        "static",
        "animated"
      ],
      "scale": [
        "1.0",
        "2.0",
        "3.0"
      ],
      "theme_mode": [
        "light",
        "dark"
      ]
    },
  ],
  "template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}"
}

Get Global Emotes

✎

Gets all global emotes. Global emotes are Twitch-created emoticons that users can use in any Twitch chat.

Learn More

Authorization

Requires a user or application OAuth access token.

URL

GET https://api.twitch.tv/helix/chat/emotes/global

Response Fields

Parameter	Type	Description
`data`	object array	The list of global emotes.
`id`	string	An ID that identifies the emote.
`name`	string	The name of the emote. This is the name that viewers type in the chat window to get the emote to appear.
`images`	object	Contains the image URLs for the emote. These image URLs will always provide a static (i.e., non-animated) emote image with a light background. NOTE: The preference is for you to use the templated URL in the `template` field to fetch the image instead of using these URLs.
`url_1x`	string	A URL to the small version (28px x 28px) of the emote.
`url_2x`	string	A URL to the medium version (56px x 56px) of the emote.
`url_4x`	string	A URL to the large version (112px x 112px) of the emote.
`format`	string array	The formats that the emote is available in. For example, if the emote is available only as a static PNG, the array contains only `static`. But if it’s available as a static PNG and an animated GIF, the array contains `static` and `animated`. The possible formats are: animated — Indicates an animated GIF is available for this emote. static — Indicates a static PNG file is available for this emote.
`scale`	string array	The sizes that the emote is available in. For example, if the emote is available in small and medium sizes, the array contains 1.0 and 2.0. Possible sizes are: 1.0 — A small version (28px x 28px) is available. 2.0 — A medium version (56px x 56px) is available. 3.0 — A large version (112px x 112px) is available.
`theme_mode`	string array	The background themes that the emote is available in. Possible themes are: dark light
`template`	string	A templated URL. Use the values from `id`, `format`, `scale`, and `theme_mode` to replace the like-named placeholder strings in the templated URL to create a CDN (content delivery network) URL that you use to fetch the emote. For information about what the template looks like and how to use it to fetch emotes, see Emote CDN URL format.

Response Codes

Code	Meaning
200	Successfully returned the global emotes.
400	The request was invalid.
401	The caller failed authentication. Verify that your access token and client ID are valid.

Example Request

This example returns all global emotes.

curl -X GET 'https://api.twitch.tv/helix/chat/emotes/global' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

# Twitch CLI example that returns all global emotes.

twitch api get /chat/emotes/global

Example Response

{
  "data": [
    {
      "id": "196892",
      "name": "TwitchUnity",
      "images": {
        "url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/196892/static/light/1.0",
        "url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/196892/static/light/2.0",
        "url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/196892/static/light/3.0"
      },
      "format": [
        "static"
      ],
      "scale": [
        "1.0",
        "2.0",
        "3.0"
      ],
      "theme_mode": [
        "light",
        "dark"
      ]
    },
    ...
  ],
  "template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}"
}

Get Emote Sets

✎

Gets emotes for one or more specified emote sets.

An emote set groups emotes that have a similar context. For example, Twitch places all the subscriber emotes that a broadcaster uploads for their channel in the same emote set.

Learn More

Authorization

Requires a user or application OAuth access token.

URL

GET https://api.twitch.tv/helix/chat/emotes/set

Required Query Parameter

Parameter	Type	Description
`emote_set_id`	string	An ID that identifies the emote set. Include the parameter for each emote set you want to get. For example, `emote_set_id=1234&emote_set_id=5678`. You may specify a maximum of 25 IDs.

Return Values

Parameter	Type	Description
`data`	object array	The list of emotes found in the specified emote sets.
`id`	string	An ID that identifies the emote.
`name`	string	The name of the emote. This is the name that viewers type in the chat window to get the emote to appear.
`images`	object	Contains the image URLs for the emote. These image URLs will always provide a static (i.e., non-animated) emote image with a light background. NOTE: The preference is for you to use the templated URL in the `template` field to fetch the image instead of using these URLs.
`url_1x`	string	A URL to the small version (28px x 28px) of the emote.
`url_2x`	string	A URL to the medium version (56px x 56px) of the emote.
`url_4x`	string	A URL to the large version (112px x 112px) of the emote.
`emote_type`	string	The type of emote. The possible values are: bitstier — Indicates a Bits tier emote. follower — Indicates a follower emote. subscriptions — Indicates a subscriber emote.
`emote_set_id`	string	An ID that identifies the emote set that the emote belongs to.
`owner_id`	string	The ID of the broadcaster who owns the emote.
`format`	string array	The formats that the emote is available in. For example, if the emote is available only as a static PNG, the array contains only `static`. But if it’s available as a static PNG and an animated GIF, the array contains `static` and `animated`. The possible formats are: animated — Indicates an animated GIF is available for this emote. static — Indicates a static PNG file is available for this emote.
`scale`	string array	The sizes that the emote is available in. For example, if the emote is available in small and medium sizes, the array contains 1.0 and 2.0. Possible sizes are: 1.0 — A small version (28px x 28px) is available. 2.0 — A medium version (56px x 56px) is available. 3.0 — A large version (112px x 112px) is available.
`theme_mode`	string array	The background themes that the emote is available in. Possible themes are: dark light
`template`	string	A templated URL. Use the values from `id`, `format`, `scale`, and `theme_mode` to replace the like-named placeholder strings in the templated URL to create a CDN (content delivery network) URL that you use to fetch the emote. For information about what the template looks like and how to use it to fetch emotes, see Emote CDN URL format.

Response Codes

Code	Meaning
200	Successfully returned emotes for the specified emote set.
400	The request was invalid.
401	The caller failed authentication. Verify that your access token and client ID are valid.

Example Request

This example gets 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'

# Twithc CLI example that gets the emotes for the specified emote set.

twitch api get /chat/emotes/set -q emote_set_id=301590448

Example Response

{
  "data": [
    {
      "id": "304456832",
      "name": "twitchdevPitchfork",
      "images": {
        "url_1x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/1.0",
        "url_2x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/2.0",
        "url_4x": "https://static-cdn.jtvnw.net/emoticons/v2/304456832/static/light/3.0"
      },
      "emote_type": "subscriptions",
      "emote_set_id": "301590448",
      "owner_id": "141981764",
      "format": [
        "static"
      ],
      "scale": [
        "1.0",
        "2.0",
        "3.0"
      ],
      "theme_mode": [
        "light",
        "dark"
      ]
    },
    ...
  ],
  "template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}"
}

Get Channel Chat Badges

✎

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 or App Access Token

URL

GET https://api.twitch.tv/helix/chat/badges

Pagination Support

None.

Required Query Parameter

Parameter	Type	Description
`broadcaster_id`	string	The ID of the broadcaster whose chat badges you want to get.

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

✎

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"
        }
      ]
    },
    ...
  ]
}

Get Chat Settings

✎

Gets the broadcaster’s chat settings.

For an overview of chat settings, see Chat Commands for Broadcasters and Moderators and Moderator Preferences.

Authorization

Requires an App access token. However, to include the non_moderator_chat_delay or non_moderator_chat_delay_duration settings in the response, you must specify a User access token with scope set to moderator:read:chat_settings.

URL

GET https://api.twitch.tv/helix/chat/settings

Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster whose chat settings you want to get.
moderator_id	No	String	Required only to access the `non_moderator_chat_delay` or `non_moderator_chat_delay_duration` settings. The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token. If the broadcaster wants to get their own settings (instead of having the moderator do it), set this parameter to the broadcaster’s ID, too.

Response Body

Field	Type	Description
data	object array	The list of chat settings. The list contains a single object with all the settings.
broadcaster_id	String	The ID of the broadcaster specified in the request.
emote_mode	Boolean	A Boolean value that determines whether chat messages must contain only emotes. Is true, if only messages that are 100% emotes are allowed; otherwise, false.
follower_mode	Boolean	A Boolean value that determines whether the broadcaster restricts the chat room to followers only, based on how long they’ve followed. Is true, if the broadcaster restricts the chat room to followers only; otherwise, false. See `follower_mode_duration` for how long the followers must have followed the broadcaster to participate in the chat room.
follower_mode_duration	Integer	The length of time, in minutes, that the followers must have followed the broadcaster to participate in the chat room. See `follower_mode`. Is null if `follower_mode` is false.
moderator_id	String	The moderator’s ID. The response includes this field only if the request specifies a User access token that includes the moderator:read:chat_settings scope.
non_moderator_chat_delay	Boolean	A Boolean value that determines whether the broadcaster adds a short delay before chat messages appear in the chat room. This gives chat moderators and bots a chance to remove them before viewers can see the message. Is true, if the broadcaster applies a delay; otherwise, false. See `non_moderator_chat_delay_duration` for the length of the delay. The response includes this field only if the request specifies a user access token that includes the moderator:read:chat_settings scope and the user in the moderator_id query parameter is one of the broadcaster’s moderators.
non_moderator_chat_delay_duration	Integer	The amount of time, in seconds, that messages are delayed from appearing in chat. See `non_moderator_chat_delay`. Is null if non_moderator_chat_delay is false. The response includes this field only if the request specifies a user access token that includes the moderator:read:chat_settings scope and the user in the moderator_id query parameter is one of the broadcaster’s moderators.
slow_mode	Boolean	A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages. Is true, if the broadcaster applies a delay; otherwise, false. See `slow_mode_wait_time` for the delay.
slow_mode_wait_time	Integer	The amount of time, in seconds, that users need to wait between sending messages. See `slow_mode`. Is null if slow_mode is false.
subscriber_mode	Boolean	A Boolean value that determines whether only users that subscribe to the broadcaster’s channel can talk in the chat room. Is true, if the broadcaster restricts the chat room to subscribers only; otherwise, false.
unique_chat_mode	Boolean	A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room. Is true, if the broadcaster requires unique messages only; otherwise, false.

Response Codes

Code	Meaning
200	Success.
400	Malformed request.
401	Authentication failure.

Example Request

curl -X GET 'https://api.twitch.tv/helix/chat/settings?broadcaster_id=1234' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

{
  "data": [
    {
      "broadcaster_id": "713936733",
      "slow_mode": false,
      "slow_mode_wait_time": null,
      "follower_mode": true,
      "follower_mode_duration": 0,
      "subscriber_mode": false,
      "emote_mode": false,
      "unique_chat_mode": false,
      "non_moderator_chat_delay": true,
      "non_moderator_chat_delay_duration": 4
    }
  ]
}

Update Chat Settings

✎

Updates the broadcaster’s chat settings.

Authentication

Requires a User access token with scope set to moderator:manage:chat_settings.

URL

PATCH https://api.twitch.tv/helix/chat/settings

Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster whose chat settings you want to update.
moderator_id	Yes	String	The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token. If the broadcaster is making the update, also set this parameter to the broadcaster’s ID.

Request Body

Specify only those fields that you want to update.

Field	Type	Description
emote_mode	Boolean	A Boolean value that determines whether chat messages must contain only emotes. Set to true, if only messages that are 100% emotes are allowed; otherwise, false. Default is false.
follower_mode	Boolean	A Boolean value that determines whether the broadcaster restricts the chat room to followers only, based on how long they’ve followed. Set to true, if the broadcaster restricts the chat room to followers only; otherwise, false. Default is true. See `follower_mode_duration` for how long the followers must have followed the broadcaster to participate in the chat room.
follower_mode_duration	Integer	The length of time, in minutes, that the followers must have followed the broadcaster to participate in the chat room (see `follower_mode`). You may specify a value in the range: 0 (no restriction) through 129600 (3 months). The default is 0.
non_moderator_chat_delay	Boolean	A Boolean value that determines whether the broadcaster adds a short delay before chat messages appear in the chat room. This gives chat moderators and bots a chance to remove them before viewers can see the message. Set to true, if the broadcaster applies a delay; otherwise, false. Default is false. See `non_moderator_chat_delay_duration` for the length of the delay.
non_moderator_chat_delay_duration	Integer	The amount of time, in seconds, that messages are delayed from appearing in chat. Possible values are: 2 — 2 second delay (recommended) 4 — 4 second delay 6 — 6 second delay See `non_moderator_chat_delay`.
slow_mode	Boolean	A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages. Set to true, if the broadcaster applies a wait period messages; otherwise, false. Default is false. See `slow_mode_wait_time` for the delay.
slow_mode_wait_time	Integer	The amount of time, in seconds, that users need to wait between sending messages (see `slow_mode`). You may specify a value in the range: 3 (3 second delay) through 120 (2 minute delay). The default is 30 seconds.
subscriber_mode	Boolean	A Boolean value that determines whether only users that subscribe to the broadcaster’s channel can talk in the chat room. Set to true, if the broadcaster restricts the chat room to subscribers only; otherwise, false. Default is false.
unique_chat_mode	Boolean	A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room. Set to true, if the broadcaster requires unique messages only; otherwise, false. Default is false.

Response Body

Field	Type	Description
data	object array	The list of chat settings. The list will contain the single object with all the settings.
broadcaster_id	String	The ID of the broadcaster specified in the request.
emote_mode	Boolean	A Boolean value that determines whether chat messages must contain only emotes. Is true, if only messages that are 100% emotes are allowed; otherwise, false.
follower_mode	Boolean	A Boolean value that determines whether the broadcaster restricts the chat room to followers only, based on how long they’ve followed. Is true, if the broadcaster restricts the chat room to followers only; otherwise, false. See `follower_mode_duration` for how long the followers must have followed the broadcaster to participate in the chat room.
follower_mode_duration	Integer	The length of time, in minutes, that the followers must have followed the broadcaster to participate in the chat room. See `follower_mode`. Is null if `follower_mode` is false.
moderator_id	String	The ID of the moderator specified in the request.
non_moderator_chat_delay	Boolean	A Boolean value that determines whether the broadcaster adds a short delay before chat messages appear in the chat room. This gives chat moderators and bots a chance to remove them before viewers can see the message. Is true, if the broadcaster applies a delay; otherwise, false. See `non_moderator_chat_delay_duration` for the length of the delay.
non_moderator_chat_delay_duration	Integer	The amount of time, in seconds, that messages are delayed from appearing in chat. See `non_moderator_chat_delay`. Is null if non_moderator_chat_delay is false.
slow_mode	Boolean	A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages. Is true, if the broadcaster applies a delay; otherwise, false. See `slow_mode_wait_time` for the delay.
slow_mode_wait_time	Integer	The amount of time, in seconds, that users need to wait between sending messages. See `slow_mode`. Is null if slow_mode is false.
subscriber_mode	Boolean	A Boolean value that determines whether only users that subscribe to the broadcaster’s channel can talk in the chat room. Is true, if the broadcaster restricts the chat room to subscribers only; otherwise, false.
unique_chat_mode	Boolean	A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room. Is true, if the broadcaster requires unique messages only; otherwise, false.

Example Request

This example disables follower_mode by setting it to false.

curl -X PATCH 'https://api.twitch.tv/helix/chat/settings?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"follower_mode": false}'

To change a setting’s value, the request must specify the mode field and its corresponding value field. For example, to change the value of slow_mode_wait_time, the request must also specify slow_mode even if it’s already true.

curl -X PATCH 'https://https://api.twitch.tv/helix/chat/settings?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 8j9yq1kpl92w96trqy7sintbsihdp' \
-H 'Client-Id: 0vql4f5yqu4spo6zrz1pkumcqwa9c' \
-H 'Content-Type: application/json' \
-d '{"slow_mode": true, "slow_mode_wait_time": 10}'

Example Response

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "slow_mode": true,
      "slow_mode_wait_time": 10,
      "follower_mode": false,
      "follower_mode_duration": null,
      "subscriber_mode": false,
      "emote_mode": false,
      "unique_chat_mode": false,
      "non_moderator_chat_delay": false,
      "non_moderator_chat_delay_duration": null
    }
  ]
}

Send Chat Announcement

✎

NEW Sends an announcement to the broadcaster’s chat room.

Authorization

Requires a user access token that includes the moderator:manage:announcements scope. The ID in the moderator_id query parameter must match the user ID in the access token.

URL

POST https://api.twitch.tv/helix/chat/announcements

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that owns the chat room to send the announcement to.
moderator_id	String	Yes	The ID of a user who has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the OAuth token, which can be a moderator or the broadcaster.

Request Body Parameters

Field	Type	Required?	Description
message	String	Yes	The announcement to make in the broadcaster’s chat room. Announcements are limited to a maximum of 500 characters; announcements longer than 500 characters are truncated.
color	String	No	The color used to highlight the announcement. Possible case-sensitive values are: blue green orange purple primary (default) If `color` is set to primary or is not set, the channel’s accent color is used to highlight the announcement (see Profile Accent Color under profile settings, Channel and Videos, and Brand).

Response Body

None

Response Codes

Code	Meaning
204 No Content	Successfully sent the announcement.
400 Bad Request	Possible reasons: The `message` query parameter is required. The specified color is not valid.
401 Unauthorized	Possible reasons: The Authorization header is required and must contain a user access token. The user access token is missing the moderator:manage:announcements scope. The OAuth token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
403 Forbidden	Possible reasons: The user is not one of the broadcaster's moderators.

Example Request

Sends an announcement to the broadcaster’s chat room.

curl -X POST 'https://api.twitch.tv/helix/chat/announcements?broadcaster_id=11111&moderator_id=44444' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t' \
-H 'Content-Type: application/json' \
-d '{"message":"Hello chat!","color":"purple"}'

Get User Chat Color

✎

NEW Gets the color used for the user’s name in chat.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/chat/color

Request Query Parameters

Parameter	Type	Required?	Description
user_id	String	Yes	The ID of the user whose color you want to get. To specify more than one user, include the user_id parameter for each user to get. For example, `&user_id=1234&user_id=5678`. The maximum number of IDs that you may specify is 100. The response ignores duplicate IDs and IDs that aren’t found.

Response Body

Field	Type	Description
data	Object[]	The list of users and the color code that’s used for their name.
user_id	String	The ID of the user.
user_login	String	The user’s login name.
user_name	String	The user’s display name.
color	String	The Hex color code that the user uses in chat for their name. If the user hasn’t specified a color in their settings, the string is empty.

Response Codes

Code	Meaning
200 OK	Successfully retrieved the users’ chat color.
400 Bad Request	Possible reasons: The ID in the user_id query parameter is not valid.
401 Unauthorized	Possible reasons: The Authorization header is required and must contain an app access token or user access token. The OAuth token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.

Example Request

Gets the color code used for the specified users’ chat name.

curl -X GET 'https://api.twitch.tv/helix/chat/color?user_id=11111&user_id=44444' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t' 

Example Response

{
  "data": [
    {
      "user_id": "11111",
      "user_name": "SpeedySpeedster1",
      "user_login": "speedyspeedster1",
      "color": "#9146FF"
    },
    {
      "user_id": "44444",
      "user_name": "SpeedySpeedster2",
      "user_login": "speedyspeedster2",
      "color": ""
    }
  ]
}

Update User Chat Color

✎

NEW Updates the color used for the user’s name in chat.

Authorization

Requires a user access token that includes the user:manage:chat_color scope. The ID in the user_id query parameter must match the user ID in the access token.

URL

PUT https://api.twitch.tv/helix/chat/color

Request Query Parameters

Parameter	Type	Required?	Description
user_id	String	Yes	The ID of the user whose chat color you want to update.
color	String	Yes	The color to use for the user’s name in chat. All users may specify one of the following named color values. blue blue_violet cadet_blue chocolate coral dodger_blue firebrick golden_rod green hot_pink orange_red red sea_green spring_green yellow_green Turbo and Prime users may specify a named color or a Hex color code like #9146FF. If you use a Hex color code, remember to URL encode it.

Response Body

None

Response Codes

Code	Meaning
204 No Content	Successfully updated the user’s chat color.
400 Bad Request	Possible reasons: The ID in the user_id query parameter is not valid. The color query parameter is required. The named color in the color query parameter is not valid. To specify a Hex color code, the user must be a Turbo or Prime user.
401 Unauthorized	Possible reasons: The Authorization header is required and must contain a user access token. The user access token is missing the user:manage:chat_color scope. The OAuth token is not valid. The ID in the user_id query parameter must match the user ID in the access token. The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.

Example Request

Uses a named color to change the color that the user uses for their name in chat.

curl -X PUT 'https://api.twitch.tv/helix/chat/color?user_id=123&color=blue' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t' 

Uses a color Hex code to change the color that the user uses for their name in chat.

curl -X PUT 'https://api.twitch.tv/helix/chat/color?user_id=123&color=%239146FF' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t' 

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. This field contains an empty string if the video is not available.
`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).
`vod_offset`	int	The zero-based offset, in seconds, to where the clip starts in the video (VOD). Is null if the video is not available or hasn’t been created yet from the live stream. See `video_id`. Note that there’s a delay between when a clip is created during a broadcast and when the offset is set. During the delay period, `vod_offset` is null. The delay is indeterminant but is typically minutes long.
`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,
      "vod_offset": 480
    }
  ]
}

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": "",
      "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,
      "vod_offset": 1957
    },
    ...
  ],
  "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=code2` 1-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

User OAuth Token or App Access Token

Authorization

The client ID associated with the access token must have ownership of the game:

Client ID > Organization ID > Game ID

Pagination support

Forward only

URL

GET https://api.twitch.tv/helix/entitlements/drops

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.
`fulfillment_status`	string	An optional fulfillment status used to filter entitlements. Valid values are `"CLAIMED"` or `"FULFILLED"`.
`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.
`fulfillment_status`	string	The fulfillment status of the entitlement as determined by the game developer. Valid values are `"CLAIMED"` or `"FULFILLED"`.
`updated_at`	string	UTC timestamp in ISO format for when this entitlement was last updated.
`pagination`	object	A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.

Response Codes

Code	Meaning
200	Entitlements retrieved successfully.
400	A malformed requestion, invalide user ID, or invalid game ID.
401	Authorization failed.
500	Internal server error.

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",
      "fulfillment_status": "CLAIMED",
      "updated_at": "2019-01-28T04:17:53.325Z"
    },
    {
      "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",
      "fulfillment_status": "CLAIMED",
      "updated_at": "2021-06-15T04:16:53.325Z"
    },
    {
      "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",
      "fulfillment_status": "FULFILLED",
      "updated_at": "2019-01-28T04:17:53.325Z"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudW..."
  }
}

Update Drops Entitlements

✎

Updates the fulfillment status on a set of Drops entitlements, specified by their entitlement IDs.

Authentication

User OAuth Token or App Access Token

Authorization

The client ID associated with the access token must have ownership of the game:

Client ID > Organization ID > Game ID

URL

PATCH https://api.twitch.tv/helix/entitlements/drops

Optional Body Parameters

Parameter	Type	Description
`entitlement_ids`	array	An array of unique identifiers of the entitlements to update. Maximum: 100.
`fulfillment_status`	string	A fulfillment status. Valid values are `"CLAIMED"` or `"FULFILLED"`.

Valid combinations of requests are:

Authorization Provided	Data Returned
App Access OAuth Token	All entitlements with benefits owned by your organization.
User OAuth Token	All entitlements owned by that user with benefits owned by your organization.

Return Values

Parameter	Type	Description
`data`	array	Array of entitlement update statuses.
`status`	string	Status code applied to a set of entitlements for the update operation that can be used to indicate partial success. Valid values are: `SUCCESS`: Entitlement was successfully updated. `INVALID_ID`: Invalid format for entitlement ID. `NOT_FOUND`: Entitlement ID does not exist. `UNAUTHORIZED`: Entitlement is not owned by the organization or the user when called with a user OAuth token. `UPDATE_FAILED`: Indicates the entitlement update operation failed. Errors in the this state are expected to be be transient and should be retried later.
`ids`	array	Array of unique identifiers of the entitlements for the specified status.

Response Codes

Code	Meaning
200	Entitlement updated successfully.
400	Bad request.
401	Authorization failed.
500	Internal server error.

Example Request

curl -H PATCH 'helix/entitlements/drops' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "fulfillment_status": "FULFILLED",
  "entitlement_ids": [
    "fb78259e-fb81-4d1b-8333-34a06ffc24c0",
    "862750a5-265e-4ab6-9f0a-c64df3d54dd0",
    "d8879baa-3966-4d10-8856-15fdd62cce02",
    "9a290126-7e3b-4f66-a9ae-551537893b65"
  ]
}'

Example Response

{
  "data": [
    {
      "status": "SUCCESS",
      "ids": [
        "fb78259e-fb81-4d1b-8333-34a06ffc24c0", "862750a5-265e-4ab6-9f0a-c64df3d54dd0"
      ]
    },
    {
      "status": "UNAUTHORIZED",
      "ids": [
        "d8879baa-3966-4d10-8856-15fdd62cce02"
      ]
    },
    {
      "status": "UPDATE_FAILED",
      "ids": [
        "9a290126-7e3b-4f66-a9ae-551537893b65"
      ]
    }
  ]
}

Redeem Code

✎

Redeems one or more redemption codes. Redeeming a code credits the user’s account with the entitlement associated with the code. For example, a Bits reward earned when playing a game.

Rate limit: You may send at most one request per second per user.

URL

POST https://api.twitch.tv/helix/entitlements/codes

Authentication

Requires an App access token. Only client IDs approved by Twitch may redeem codes on behalf of any Twitch user account.

Query Parameters

Parameter	Type	Description
`code`	String	The redemption code to redeem. To redeem multiple codes, include this parameter for each redemption code. For example, `code=1234&code=5678`. You may specify a maximum of 20 codes.
`user_id`	String	The ID of the user that owns the redemption code to redeem.

Return Values

Parameter	Type	Description
`data`	Object array	The list of redeemed codes.
`code`	String	The redemption code.
`status`	String	The redemption code’s status. Possible values are: ALREADY_CLAIMED — The code has already been claimed. All codes are single-use. EXPIRED — The code has expired and can no longer be claimed. INACTIVE — The code has not been activated. INCORRECT_FORMAT — The code is not properly formatted. INTERNAL_ERROR — An internal or unknown error occurred when accessing the code. NOT_FOUND — The code was not found. SUCCESSFULLY_REDEEMED — Successfully redeemed the code and credited the user's account with the entitlement. UNUSED — The code has not been claimed. USER_NOT_ELIGIBLE — The user is not eligible to redeem this code.

Example Request

curl -X POST 'https://api.twitch.tv/helix/entitlements/codes?user_id=12345&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"
    }
  ]
}

Get Extension Configuration Segment

✎

Gets the specified configuration segment from the specified extension.

NOTE: You can retrieve each segment a maximum of 20 times per minute. If you exceed the limit, the request returns HTTP status code 429. To determine when you may resume making requests, see the Ratelimit-Reset response header.

Authorization

A signed JWT created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the exp, user_id, and role fields documented in JWT Schema, and role must be set to external. For example:

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external"
}

URL

GET https://api.twitch.tv/helix/extensions/configurations

Required Query Parameters

Parameter	Type	Description
`broadcaster_id`	string	The ID of the broadcaster for the configuration returned. This parameter is required if you set the `segment` parameter to broadcaster or developer. Do not specify this parameter if you set `segment` to global.
`extension_id`	string	The ID of the extension that contains the configuration segment you want to get.
`segment`	string	The type of configuration segment to get. Valid values are: broadcaster developer global You may specify one or more segments. To specify multiple segments, include the `segment` parameter for each segment to get. For example, `segment=broadcaster&segment=developer`.

Response Fields

Name	Type	Description
`data`	object array	An array of Segment objects.
`segment`	string	The type of segment. Possible values are: broadcaster developer global
`broadcaster_id`	string	The ID of the broadcaster that owns the extension. The object includes this field only if the `segment` query parameter is set to developer or broadcaster.
`content`	string	The contents of the segment. This string may be a plain string or a string-encoded JSON object.
`version`	string	The version that identifies the segment’s definition.

Response Codes

Code	Meaning
200	Successfully retrieved the configuration.
400	The request was invalid. Confirm that you correctly specified the required query parameters.
401	Authorization failed. Invalid or expired JWT.
429	Too many requests. Check the `Ratelimit-Reset` response header to determine when you may resume making requests.

Example Request

This example gets the global configuration segment from the specified extension. Because the request gets the global segment, it must not include the broadcaster_id query parameter.

curl -X GET 'https://api.twitch.tv/helix/extensions/configurations?extension_id=<your extension id>&segment=global' \
-H 'Authorization: Bearer <your JWT token>' \
-H 'Client-Id: <your client ID>'

Example Response

The following example shows a global segment that contains a plain text string in the content field.

{
  "data": [
    {
      "segment": "global",
      "content": "hello config!",
      "version": "0.0.1"
    }
  ]
}

The following example shows a global segment that contains a string-encoded JSON object in the content field.

{
  "data": [
    {
      "segment": "global",
      "content": "{\"foo\":\"bar\"}",
      "version": "0.0.1"
    }
  ]
}

Set Extension Configuration Segment

✎

Sets a single configuration segment of any type. The segment type is specified as a body parameter.

Each segment is limited to 5 KB and can be set at most 20 times per minute. Updates to this data are not delivered to Extensions that have already been rendered.

Authorization

Signed JWT created by an Extension Backend Service (EBS), following the requirements documented in Signing the JWT. A signed JWT must include the exp, user_id, and role fields documented in JWT Schema, and role must be set to "external". For example:

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external"
}

URL

PUT https://api.twitch.tv/helix/extensions/configurations

Pagination Support

Not applicable.

Required Body Parameters

Parameter	Type	Description
`extension_id`	string	ID for the Extension which the configuration is for.
`segment`	string	Configuration type. Valid values are `"global"`, `"developer"`, or `"broadcaster"`.

Optional Body Parameters

Parameter	Type	Description
`broadcaster_id`	string	User ID of the broadcaster. Required if the segment type is `"developer"` or `"broadcaster"`.
`content`	string	Configuration in a string-encoded format.
`version`	string	Configuration version with the segment type.

Response Codes

Code	Meaning
204	The configuration was successfully stored.
400	Request was invalid.
401	Authorization failed. Invalid or expired JWT.

Example Request

curl -X PUT 'https://api.twitch.tv/helix/extensions/configurations' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "extension_id": "uo6dggojyb8d6soh92zknwmi5ej1q2",
  "segment": "global",
  "version": "0.0.1",
  "content": "hello config!"
}'

Example Response

204 No Content

Set Extension Required Configuration

✎

Enable activation of a specified Extension, after any required broadcaster configuration is correct. The Extension is identified by a client ID value assigned to the Extension when it is created. This is for Extensions that require broadcaster configuration before activation. Use this if, in Extension Capabilities, you select Custom/My Own Service.

You enforce required broadcaster configuration with a required_configuration string in the Extension manifest. The contents of this string can be whatever you want. Once your EBS determines that the Extension is correctly configured on a channel, use this endpoint to provide that same configuration string, which enables activation on the channel. The endpoint URL includes the channel ID of the page where the Extension is iframe embedded.

If a future version of the Extension requires a different configuration, change the required_configuration string in your manifest. When the new version is released, broadcasters will be required to re-configure that new version.

Authorization

Signed JWT created by an Extension Backend Service (EBS), following the requirements documented in Signing the JWT. A signed JWT must include the exp, user_id, and role fields documented in JWT Schema, and role must be set to "external". For example:

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external"
}

URL

PUT https://api.twitch.tv/helix/extensions/required_configuration

Pagination Support

Not applicable.

Required Query Parameters

Parameter	Type	Description
`broadcaster_id`	string	User ID of the broadcaster who has activated the specified Extension on their channel.

Required Body Parameters

Parameter	Type	Description
`extension_id`	string	ID for the Extension to activate.
`extension_version`	string	The version fo the Extension to release.
`required_configuration`	string	The version of the configuration to use with the Extension.

Response Codes

Code	Meaning
204	Extension activated successfully.
400	Request was invalid.
401	Authorization failed. Invalide or expired JWT.

Example Request

curl -X PUT 'https://api.twitch.tv/helix/extensions/required_configuration?broadcaster_id=274637212' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "required_configuration": "RCS",
  "extension_id": "uo6dggojyb8d6soh92zknwmi5ej1q2",
  "extension_version": "0.0.1"
}'

Example Response

204 No Content

Send Extension PubSub Message

✎

Twitch provides a publish-subscribe system for your EBS to communicate with both the broadcaster and viewers. Calling this endpoint forwards your message using the same mechanism as the send JavaScript helper function. A message can be sent to either a specified channel or globally (all channels on which your extension is active).

Extension PubSub has a rate limit of 100 requests per minute for a combination of Extension client ID and broadcaster ID.

Authorization

Signed JWT created by an Extension Backend Service (EBS), following the requirements documented in Signing the JWT. A signed JWT must include the channel_id and pubsub_perms fields documented in JWT Schema. For example:

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external",
  "channel_id": "27419011",
  "pubsub_perms": {
    "send":[
      "broadcast"
    ]
  }
}

To send globally:

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external",
  "channel_id": "all",
  "pubsub_perms": {
    "send":[
      "global"
    ]
  }
}

URL

POST https://api.twitch.tv/helix/extensions/pubsub

Pagination Support

Not applicable.

Required Body Parameters

Parameter	Type	Description
`target`	array	Array of strings for valid PubSub targets. Valid values: `"broadcast"`, `"global"`, `"whisper-<user-id>"`
`broadcaster_id`	string	ID of the broadcaster receiving the payload. This is not required if `is_global_broadcast` is set to `true`.
`is_global_broadcast`	boolean	Indicates if the message should be sent to all channels where your Extension is active. Default: `false`.
`message`	string	String-encoded JSON message to be sent. The message is limited to a maximum of 5 KB.

Response Codes

Code	Meaning
204	The message was published successfully.
400	Request was invalid.
401	Authorization failed. Invalide or expired JWT.

Example Request

curl -X POST 'https://api.twitch.tv/helix/extensions/pubsub' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "message": "hello world!",
  "broadcaster_id": "141981764",
  "target": ["broadcast"]
}'

Example Response

204 No Content

Get Extension Live Channels

✎

Returns one page of live channels that have installed or activated a specific Extension, identified by a client ID value assigned to the Extension when it is created. A channel that recently went live may take a few minutes to appear in this list, and a channel may continue to appear on this list for a few minutes after it stops broadcasting.

Authorization

User OAuth Token or App Access Token

URL

GET https://api.twitch.tv/helix/extensions/live

Pagination Support

Forward pagination.

Required Query Parameters

Parameter	Type	Description
`extension_id`	string	ID of the Extension to search for.

Optional Query Parameters

Parameter	Type	Description
`first`	integer	Maximum number of objects to return. Maximum: 100. Default: 20.
`after`	string	The cursor used to fetch the next page of data.

Return Values

Parameter	Type	Description
`title`	string	Title of the stream.
`broadcaster_id`	string	User ID of the broadcaster.
`broadcaster_name`	string	Broadcaster’s display name.
`game_name`	string	Name of the game being played.
`game_id`	string	ID of the game being played.

Response Codes

Code	Meaning
200	List of live channels returned successfully.
400	Request was invalid.
401	Authorization failed.

Example Request

curl -X GET 'https://api.twitch.tv/helix/extensions/live?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "broadcaster_id": "252766116",
      "broadcaster_name": "swoosh_xii",
      "game_name": "Tom Clancy's Rainbow Six Siege",
      "game_id": "460630",
      "title": "[PS4] ITA/ENG UNRANKED CHILLIN' (SUB 1/15) - !instagram !donation !sens !team !youtube"
    },
    {
      "broadcaster_id": "264525686",
      "broadcaster_name": "gaddem_",
      "game_name": "For Honor",
      "game_id": "490382",
      "title": "any Kätzchen ? - 680 Rep + > Kompetitive Kitten"
    },
    {
      "broadcaster_id": "264787895",
      "broadcaster_name": "LenhadorGameplay",
      "game_name": "For Honor",
      "game_id": "490382",
      "title": "Vazou o novo personagem! *Triste*"
    }
  ],
  "pagination": "YVc1emRHRnNiQ015TmpJek5qazVOVHBoYWpKbGRIZDFaR0Z5YjNCMGN6UTJNMkZ1TUdwM2FHWnBZbm8yYW5rNjoy"
}

Get Extension Secrets

✎

Retrieves a specified Extension’s secret data consisting of a version and an array of secret objects. Each secret object contains a base64-encoded secret, a UTC timestamp when the secret becomes active, and a timestamp when the secret expires.

Authorization

Signed JWT created by an Extension Backend Service (EBS), following the requirements documented in Signing the JWT. A signed JWT must include the exp, user_id, and role fields documented in JWT Schema, and role must be set to "external". For example:

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external"
}

URL

GET https://api.twitch.tv/helix/extensions/jwt/secrets

Pagination Support

None.

Return Values

Parameter	Type	Description
`format_version`	integer	Indicates the version associated with the Extension secrets in the response.
`secrets`	array	Array of secret objects.
`secrets[].content`	string	Raw secret that should be used with JWT encoding.
`secrets[].active`	string	The earliest possible time this secret is valid to sign a JWT in RFC 3339 format.
`secrets[].expires`	string	The latest possible time this secret may be used to decode a JWT in RFC 3339 format.

Response Codes

Code	Meaning
200	Extensions secrets returned successfully.
400	Request was invalid.
401	Authorization failed. Invalid or expired JWT.

Example Request

curl -X GET 'https://api.twitch.tv/helix/extensions/jwt/secrets?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "format_version": 1,
      "secrets": [
        {
          "content": "secret",
          "active_at": "2021-03-29T06:58:40.858343036Z",
          "expires_at": "2121-03-05T06:58:40.858343036Z"
        }
      ]
    }
  ]
}

Create Extension Secret

✎

Creates a JWT signing secret for a specific Extension. Also rotates any current secrets out of service, with enough time for instances of the Extension to gracefully switch over to the new secret. Use this function only when you are ready to install the new secret it returns.

Authorization

Signed JWT created by an Extension Backend Service (EBS), following the requirements documented in Signing the JWT. A signed JWT must include the exp, user_id, and role fields documented in JWT Schema, and role must be set to "external". For example:

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external"
}

URL

POST https://api.twitch.tv/helix/extensions/jwt/secrets

Pagination Support

Not applicable.

Required Query Parameters

Parameter	Type	Description
`extension_id`	string	The ID of the extension to apply the shared secret to.

Optional Query Parameters

Parameter	Type	Description
`delay`	integer	JWT signing activation delay for the newly created secret in seconds. Minimum: 300. Default: 300.

Return Values

Parameter	Type	Description
`format_version`	integer	Indicates the version associated with the Extension secrets in the response.
`secrets`	array	Array of secret objects.
`secrets[].content`	string	Raw secret that should be used with JWT encoding.
`secrets[].active`	string	The earliest possible time this secret is valid to sign a JWT in RFC 3339 format.
`secrets[].expires`	string	The latest possible time this secret may be used to decode a JWT in RFC 3339 format.

Response Codes

Code	Meaning
200	A new secret was created successfully.
400	Request was invalid.
401	Authorization failed. Invalid or expired JWT.

Example Request

curl -X POST 'https://api.twitch.tv/helix/extensions/jwt/secrets?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2&delay=600' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "format_version": 1,
      "secrets": [
        {
          "content": "old-secret",
          "active_at": "2021-03-29T06:58:40.858343036Z",
          "expires_at": "2021-04-22T05:21:54.99261682Z"
        },
        {
          "content": "new-secret",
          "active_at": "2021-04-22T04:16:54.996365329Z",
          "expires_at": "2121-03-29T04:16:54.996365329Z"
        }
      ]
    }
  ]
}

Send Extension Chat Message

✎

Sends a specified chat message to a specified channel. The message will appear in the channel’s chat as a normal message. The “username” of the message is the Extension name.

There is a limit of 12 messages per minute, per channel. Extension chat messages use the same rate-limiting functionality as the Twitch API (see Rate Limits).

Authorization

Signed JWT created by an Extension Backend Service (EBS), following the requirements documented in Signing the JWT. The signed JWT must include the role field (set to external) and the user_id field.

URL

POST https://api.twitch.tv/helix/extensions/chat

Pagination Support

Not applicable.

Required Query Parameters

Parameter	Type	Description
`broadcaster_id`	string	User ID of the broadcaster whose channel has the Extension activated.

Required Body Parameters

Parameter	Type	Description
`text`	string	Message for Twitch chat. Maximum: 280 characters.
`extension_id`	string	Client ID associated with the Extension.
`extension_version`	string	Version of the Extension sending this message.

Response Codes

Code	Meaning
204	Chat message was published to the channel successfully.
400	Request was invalid.
401	Authorization failed. Invalid or expired JWT.

Example Request

curl -X POST 'https://api.twitch.tv/helix/extensions/chat?broadcaster_id=237757755' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "text": "Hello",
  "extension_id": "uo6dggojyb8d6soh92zknwmi5ej1q2",
  "extension_version": "0.0.9"
}

Example Response

204 No Content

Get Extensions

✎

Gets information about your Extensions; either the current version or a specified version.

Authorization

Signed JWT created by an Extension Backend Service (EBS), following the requirements documented in Signing the JWT. A signed JWT must include the role field documented in JWT Schema, and role must be set to "external".

URL

GET https://api.twitch.tv/helix/extensions

Pagination Support

None.

Required Query Parameters

Parameter	Type	Description
`extension_id`	string	ID of the Extension.

Optional Query Parameters

Parameter	Type	Description
`extension_version`	string	The specific version of the Extension to return. If not provided, the current version is returned.

Return Values

Parameter	Type	Description
`author_name`	string	Name of the individual or organization that owns the Extension.
`bits_enabled`	boolean	Whether the Extension has features that use Bits.
`can_install`	boolean	Indicates if a user can install the Extension on their channel. They may not be allowed if the Extension is currently in testing mode and the user is not on the allow list.
`configuration_location`	string	Whether the Extension configuration is hosted by the EBS or the Extensions Configuration Service.
`description`	string	The description of the Extension.
`eula_tos_url`	string	URL to the Extension’s Terms of Service.
`has_chat_support`	boolean	Indicates if the Extension can communicate with the installed channel’s chat.
`icon_url`	string	The default icon to be displayed in the Extensions directory.
`icon_urls`	object	The default icon in a variety of sizes.
`id`	string	The autogenerated ID of the Extension.
`name`	string	The name of the Extension.
`privacy_policy_url`	string	URL to the Extension’s privacy policy.
`request_identity_link`	boolean	Indicates if the Extension wants to explicitly ask viewers to link their Twitch identity.
`screenshot_urls`	array	Screenshots to be shown in the Extensions marketplace.
`state`	string	The current state of the Extension. Valid values are `"InTest"`, `"InReview"`, `"Rejected"`, `"Approved"`, `"Released"`, `"Deprecated"`, `"PendingAction"`, `"AssetsUploaded"`, `"Deleted"`.
`subscriptions_support_level`	string	Indicates if the Extension can determine a user’s subscription level on the channel the Extension is installed on.
`summary`	string	A brief description of the Extension.
`support_email`	string	The email users can use to receive Extension support.
`version`	string	The version of the Extension.
`viewer_summary`	string	A brief description displayed on the channel to explain how the Extension works.
`views`	object	All configurations related to views such as: mobile, panel, video_overlay, and component.
`allowlisted_config_urls`	array	Allow-listed configuration URLs for displaying the Extension.
`allowlisted_panel_urls`	array	Allow-listed panel URLs for displaying the Extension.

Response Codes

Code	Meaning
200	Extension details returned successfully.
400	Request was invalid.
401	Authorization failed.

Example Request

curl -X GET 'https://api.twitch.tv/helix/extensions?extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2&extension_version=0.0.9' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "author_name": "Twitch Developers",
      "bits_enabled": true,
      "can_install": false,
      "configuration_location": "hosted",
      "description": "An extension for testing all the features that we add to extensions",
      "eula_tos_url": "",
      "has_chat_support": true,
      "icon_url": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/logob6c995d8-8b45-48cc-a748-b256e92ac1cd",
      "icon_urls": {
        "100x100": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/logob6c995d8-8b45-48cc-a748-b256e92ac1cd",
        "24x24": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/taskbar905b19da-e7e5-4d8f-beb7-f543a861ac1e",
        "300x200": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/discoveryd9545b2c-5474-46d7-a523-1c3835d862ce"
      },
      "id": "pgn0bjv51epi7eaekt53tovjnc82qo",
      "name": "Official Developers Demo",
      "privacy_policy_url": "",
      "request_identity_link": true,
      "screenshot_urls": [
        "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/screenshotbdec475d-3d2f-4378-b334-941dfddc897a"
      ],
      "state": "Released",
      "subscriptions_support_level": "optional",
      "summary": "Test ALL the extensions features!",
      "support_email": "dx-extensions-test-dev@justin.tv",
      "version": "0.0.9",
      "viewer_summary": "Test ALL the extensions features!",
      "views": {
        "mobile": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html"
        },
        "panel": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
          "height": 300,
          "can_link_external_content": false
        },
        "video_overlay": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
          "can_link_external_content": false
        },
        "component": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
          "aspect_width": 0,
          "aspect_height": 0,
          "aspect_ratio_x": 48000,
          "aspect_ratio_y": 36000,
          "autoscale": true,
          "scale_pixels": 1024,
          "target_height": 5333,
          "size": 0,
          "zoom": false,
          "zoom_pixels": 0,
          "can_link_external_content": false
        }
      },
      "allowlisted_config_urls": [],
      "allowlisted_panel_urls": []
    }
  ]
}

Get Released Extensions

✎

Gets information about a released Extension; either the current version or a specified version.

Authorization

User OAuth Token or App Access Token

URL

GET https://api.twitch.tv/helix/extensions/released

Pagination Support

None.

Required Query Parameters

Parameter	Type	Description
`extension_id`	string	ID of the Extension.

Optional Query Parameters

Parameter	Type	Description
`extension_version`	string	The specific version of the Extension to return. If not provided, the current version is returned.

Return Values

Parameter	Type	Description
`author_name`	string	Name of the individual or organization that owns the Extension.
`bits_enabled`	boolean	Whether the Extension has features that use Bits.
`can_install`	boolean	Indicates if a user can install the Extension on their channel. They may not be allowed if the Extension is currently in testing mode and the user is not on the allow list.
`configuration_location`	string	Whether the Extension configuration is hosted by the EBS or the Extensions Configuration Service.
`description`	string	The description of the Extension.
`eula_tos_url`	string	URL to the Extension’s Terms of Service.
`has_chat_support`	boolean	Indicates if the Extension can communicate with the installed channel’s chat.
`icon_url`	string	The default icon to be displayed in the Extensions directory.
`icon_urls`	object	The default icon in a variety of sizes.
`id`	string	The autogenerated ID of the Extension.
`name`	string	The name of the Extension.
`privacy_policy_url`	string	URL to the Extension’s privacy policy.
`request_identity_link`	boolean	Indicates if the Extension wants to explicitly ask viewers to link their Twitch identity.
`screenshot_urls`	array	Screenshots to be shown in the Extensions marketplace.
`state`	string	The current state of the Extension. Valid values are `"InTest"`, `"InReview"`, `"Rejected"`, `"Approved"`, `"Released"`, `"Deprecated"`, `"PendingAction"`, `"AssetsUploaded"`, `"Deleted"`.
`subscriptions_support_level`	object	Indicates if the Extension can determine a user’s subscription level on the channel the Extension is installed on.
`summary`	string	A brief description of the Extension.
`support_email`	string	The email users can use to receive Extension support.
`version`	string	The version of the Extension.
`viewer_summary`	string	A brief description displayed on the channel to explain how the Extension works.
`views`	object	All configurations related to views such as: mobile, panel, video_overlay, and component.
`allowlisted_config_urls`	array	Allow-listed configuration URLs for displaying the Extension.
`allowlisted_panel_urls`	array	Allow-listed panel URLs for displaying the Extension.

Response Codes

Code	Meaning
200	Extension details returned successfully.
400	Request was invalid.
401	Authorization failed.

Example Request

curl -X GET 'https://api.twitch.tv/helix/extensions/released?extension_version=0.0.9&extension_id=uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "author_name": "Twitch Developer Experience",
      "bits_enabled": true,
      "can_install": false,
      "configuration_location": "hosted",
      "description": "An extension for testing all the features that we add to extensions",
      "eula_tos_url": "",
      "has_chat_support": true,
      "icon_url": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/logob6c995d8-8b45-48cc-a748-b256e92ac1cd",
      "icon_urls": {
        "100x100": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/logob6c995d8-8b45-48cc-a748-b256e92ac1cd",
        "24x24": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/taskbar905b19da-e7e5-4d8f-beb7-f543a861ac1e",
        "300x200": "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/discoveryd9545b2c-5474-46d7-a523-1c3835d862ce"
      },
      "id": "pgn0bjv51epi7eaekt53tovjnc82qo",
      "name": "Official Developer Experience Demo",
      "privacy_policy_url": "",
      "request_identity_link": true,
      "screenshot_urls": [
        "https://extensions-discovery-images.twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.8/screenshotbdec475d-3d2f-4378-b334-941dfddc897a"
      ],
      "state": "Released",
      "subscriptions_support_level": "optional",
      "summary": "Test ALL the extensions features!",
      "support_email": "dx-extensions-test-dev@justin.tv",
      "version": "0.0.9",
      "viewer_summary": "Test ALL the extensions features!",
      "views": {
        "mobile": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html"
        },
        "panel": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
          "height": 300,
          "can_link_external_content": false
        },
        "video_overlay": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
          "can_link_external_content": false
        },
        "component": {
          "viewer_url": "https://pgn0bjv51epi7eaekt53tovjnc82qo.ext-twitch.tv/pgn0bjv51epi7eaekt53tovjnc82qo/0.0.9/f9a0d8aae0f9dd0b2d6ef3416b96bc79/index.html",
          "aspect_width": 0,
          "aspect_height": 0,
          "aspect_ratio_x": 48000,
          "aspect_ratio_y": 36000,
          "autoscale": true,
          "scale_pixels": 1024,
          "target_height": 5333,
          "size": 0,
          "zoom": false,
          "zoom_pixels": 0,
          "can_link_external_content": false
        }
      },
      "allowlisted_config_urls": [],
      "allowlisted_panel_urls": []
    }
  ]
}

Get Extension Bits Products

✎

Gets a list of Bits products that belongs to an Extension.

Authorization

App Access Token associated with the Extension client ID

URL

GET https://api.twitch.tv/helix/bits/extensions

Pagination Support

None.

Optional Query Parameters

Parameter	Type	Description
`should_include_all`	boolean	Whether Bits products that are disabled/expired should be included in the response. Default: `false`.

Return Values

Parameter	Type	Description
`sku`	string	SKU of the Bits product. This is unique across all products that belong to an Extension.
`cost`	object	Object containing cost information.
`cost.amount`	integer	Number of Bits for which the product will be exchanged.
`cost.type`	string	Cost type. The one valid value is `"bits"`.
`in_development`	boolean	Indicates if the product is in development and not yet released for public use.
`display_name`	string	Name of the product to be displayed in the Extension.
`expiration`	string	Expiration time for the product in RFC3339 format.
`is_broadcast`	boolean	Indicates if Bits product purchase events are broadcast to all instances of an Extension on a channel via the “onTransactionComplete” helper callback.

Response Codes

Code	Meaning
200	List of Bits products returned successfully.
400	Request was invalid.
401	Authorization failed.

Example Request

curl -X GET 'https://api.twitch.tv/helix/bits/extensions?should_include_all=true' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "sku": "1010",
      "cost": {
        "amount": 990,
        "type": "bits"
      },
      "in_development": true,
      "display_name": "Rusty Crate 2",
      "expiration": "2021-05-18T09:10:13.397Z",
      "is_broadcast": false
    }
  ]
}

Update Extension Bits Product

✎

Add or update a Bits products that belongs to an Extension.

Authorization

App Access Token associated with the Extension client ID

URL

PUT https://api.twitch.tv/helix/bits/extensions

Pagination Support

Not applicable.

Required Body Parameters

Parameter	Type	Description
`sku`	string	SKU of the Bits product. This must be unique across all products that belong to an Extension. The SKU cannot be changed after saving. Maximum: 255 characters, no white spaces.
`cost`	object	Object containing cost information.
`cost.amount`	integer	Number of Bits for which the product will be exchanged. Minimum: 1, Maximum: 10000.
`cost.type`	string	Cost type. The one valid value is `"bits"`.
`display_name`	string	Name of the product to be displayed in the Extension. Maximum: 255 characters.

Optional Body Parameters

Parameter	Type	Description
`in_development`	boolean	Set to `true` if the product is in development and not yet released for public use. Default: `false`.
`expiration`	string	Expiration time for the product in RFC3339 format. If not provided, the Bits product will not have an expiration date. Setting an expiration in the past will disable the product.
`is_broadcast`	boolean	Indicates if Bits product purchase events are broadcast to all instances of an Extension on a channel via the “onTransactionComplete” helper callback. Default: `false`.

Return Values

Parameter	Type	Description
`sku`	string	SKU of the Bits product. This is unique across all products that belong to an Extension.
`cost`	object	Object containing cost information.
`cost.amount`	integer	Number of Bits for which the product will be exchanged.
`cost.type`	string	Cost type. The one valid value is `"bits"`.
`in_development`	boolean	Indicates if the product is in development and not yet released for public use.
`display_name`	string	Name of the product to be displayed in the Extension.
`expiration`	string	Expiration time for the product in RFC3339 format.
`is_broadcast`	boolean	Indicates if Bits product purchase events are broadcast to all instances of an Extension on a channel via the “onTransactionComplete” helper callback.

Response Codes

Code	Meaning
200	Bits product added or updated successfully.
400	Request was invalid.
401	Authorization failed.

Example Request

curl -X PUT 'https://api.twitch.tv/helix/bits/extensions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d {
  "sku": "1010",
  "cost": {
    "amount": 990,
    "type": "bits"
  },
  "in_development": true,
  "display_name": "Rusty Crate 2",
  "is_broadcast": true,
  "expiration": "2021-05-18T09:10:13.397Z"
}

Example Response

{
  "data": [
    {
      "sku": "1010",
      "cost": {
        "amount": 990,
        "type": "bits"
      },
      "in_development": true,
      "display_name": "Rusty Crate 2",
      "expiration": "2021-05-18T09:10:13.397Z",
      "is_broadcast": true
    }
  ]
}

Create EventSub Subscription

✎

Creates an EventSub subscription.

Authentication

Requires an app access token.

To create a subscription, you must use an app access token; however, if the subscription type requires user authorization, the user must have granted your app permissions to receive those events before you subscribe to them. For example, to subscribe to channel.subscribe events, the user must have granted your app permission which adds the channel:read:subscriptions scope to your app’s client ID.

URL

POST https://api.twitch.tv/helix/eventsub/subscriptions

Required Query Parameters

None

Required Body Parameters

Parameter	Type	Description
`type`	string	The type of subscription to create. For a list of subscriptions you can create, see Subscription Types. Set `type` to the value in the Name column of the Subscription Types table.
`version`	string	The version of the subscription type used in this request. A subscription type could define one or more object definitions, so you need to specify which definition you’re using.
`condition`	condition	The parameter values that are specific to the specified subscription type.
`transport`	transport	The transport details, such as the transport method and callback URL, that you want Twitch to use when sending you notifications.

Response Fields

Field	Type	Description
`data`	object array	An array of subscription objects. The array will contain only one element.
`id`	string	An ID that identifies the subscription.
`status`	string	The status of the create subscription request. Possible values are: enabled — The subscription is enabled. webhook_callback_verification_pending — The subscription is pending verification of the specified callback URL. To determine if the subscription moved from pending to another state, send a GET request and use the ID to find the subscription in the list. webhook_callback_verification_failed — The specified callback URL failed verification. notification_failures_exceeded — The notification delivery failure rate was too high. authorization_revoked — The authorization was revoked for one or more users specified in the Condition object. user_removed — One of the users specified in the Condition object was removed.
`type`	string	The type of subscription.
`version`	string	The version of the subscription type.
`condition`	condition	The parameter values for the subscription type.
`created_at`	string	The RFC 3339 timestamp indicating when the subscription was created.
`transport`	transport	The transport details used to send you notifications.
`cost`	integer	The amount that the subscription counts against your limit. Learn More
`total`	integer	The total number of subscriptions you’ve created.
`total_cost`	integer	The sum of all of your subscription costs. Learn More
`max_total_cost`	integer	The maximum total cost that you may incur for all subscriptions you create.

Response Codes

Code	Meaning
202	Successfully created the subscription.
400	The request was invalid.
401	The caller failed authentication. Verify that your access token and client ID are valid.
403	The caller is not authorized to subscribe to the event.
409	The subscription already exists.
429	The request exceeds the number of subscriptions that you may create with the same `type` and `condition` values.

Example Request

This example adds a user.update subscription.

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":"user.update","version":"1","condition":{"user_id":"1234"},"transport":{"method":"webhook","callback":"https://this-is-a-callback.com","secret":"s3cre7"}}' 

# Twitch CLI example that adds a user.update subscription.

twitch api post /eventsub/subscriptions -b '{"type":"user.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": "user.update",
      "version": "1",
      "condition": {
        "user_id": "1234"
      },
      "created_at": "2020-11-10T14:32:18.730260295Z",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback.com"
      },
      "cost": 1
    }
  ],
  "total": 1,
  "total_cost": 1,
  "max_total_cost": 10000
}

Delete EventSub Subscription

✎

Deletes an EventSub subscription.

Authentication

Requires an application OAuth access token.

URL

DELETE https://api.twitch.tv/helix/eventsub/subscriptions

Required Query Parameters

Name	Type	Description
`id`	string	The ID of the subscription to delete. This is the ID that Create Eventsub Subscription returns.

Response Fields

None

Response Codes

Code	Meaning
204	Successfully deleted the subscription.
404	The subscription was not found.
401	The caller failed authentication. Verify that your access token and client ID are valid.

Example Request

This example deletes the specified 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' 

# Twitch CLI example that deletes the specified subscription.

twitch api delete /eventsub/subscriptions -q id=c839a466-034a-4d77-8d4d-c9a751516e7

Example Response

The response body is empty.

Get EventSub Subscriptions

✎

Gets a list of your EventSub subscriptions. The list is paginated and ordered by the oldest subscription first.

Authentication

Requires an application OAuth access token.

URL

GET https://api.twitch.tv/helix/eventsub/subscriptions

Required Query Parameters

None

Optional Query Parameters

Use the status, type, and user_id query parameters to filter the list of subscriptions that are returned. The filters are mutually exclusive; the request fails if you specify more than one filter.

Parameter	Type	Description
`status`	string	Filter subscriptions by its status. Possible values are: enabled — The subscription is enabled. webhook_callback_verification_pending — The subscription is pending verification of the specified callback URL. webhook_callback_verification_failed — The specified callback URL failed verification. notification_failures_exceeded — The notification delivery failure rate was too high. authorization_revoked — The authorization was revoked for one or more users specified in the Condition object. user_removed — One of the users specified in the Condition object was removed.
`type`	string	Filter subscriptions by subscription type (e.g., `channel.update`). For a list of subscription types, see Subscription Types.
`user_id`	string	Filter subscriptions by user ID. The response contains subscriptions where the user ID matches a user ID that you specified in the Condition object when you created the subscription.
`after`	string	The cursor used to get the next page of results. The `pagination` object in the response contains the cursor’s value.

Response Fields

Field	Type	Description
`data`	object array	An array of subscription objects. The list is empty if you don’t have any subscriptions.
`id`	string	An ID that identifies the subscription.
`status`	string	The subscription’s status. Possible values are: enabled — The subscription is enabled. webhook_callback_verification_pending — The subscription is pending verification of the specified callback URL. webhook_callback_verification_failed — The specified callback URL failed verification. notification_failures_exceeded — The notification delivery failure rate was too high. authorization_revoked — The authorization was revoked for one or more users specified in the Condition object. user_removed — One of the users specified in the Condition object was removed.
`type`	string	The subscription’s type.
`version`	string	The version of the subscription type.
`condition`	condition	The subscription’s parameter values.
`created_at`	string	The RFC 3339 timestamp indicating when the subscription was created.
`transport`	transport	The transport details used to send you notifications.
`cost`	integer	The amount that the subscription counts against your limit. Learn More
`total`	integer	The total number of subscriptions you’ve created.
`total_cost`	integer	The sum of all of your subscription costs. Learn More
`max_total_cost`	integer	The maximum total cost that you’re allowed to incur for all subscriptions you create.
`pagination`	object	An object that contains the cursor used to get the next page of subscriptions. The object is empty if the list of subscriptions fits on one page or there are no more pages to get. The number of subscriptions returned per page is undertermined.
`cursor`	string	The cursor value that you set the `after` query parameter to.

Response Codes

Code	Meaning
200	Successfully retrieved the subscriptions.
400	The request was invalid.
401	The caller failed authentication. Verify that your access token and client ID are valid.

Example Request

Gets a list of EventSub subscriptions that you created. The list is paginated and ordered by the oldest subscription first.

curl -X GET 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' 

# Twitch CLI example that gets a list of EventSub subscriptions that you created.

twitch api get /eventsub/subscriptions 

Example Response

{
  "total": 2,
  "data": [
    {
      "id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
      "status": "enabled",
      "type": "stream.online",
      "version": "1",
      "condition": {
        "broadcaster_user_id": "1234"
      },
      "created_at": "2020-11-10T20:08:33.12345678Z",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback.com"
      },
      "cost": 1
    },
    {
      "id": "35016908-41ff-33ce-7879-61b8dfc2ee16",
      "status": "webhook_callback_verification_pending",
      "type": "user.update",
      "version": "1",
      "condition": {
        "user_id": "1234"
      },
      "created_at": "2020-11-10T14:32:18.730260295Z",
      "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 Creator Goals

✎

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

Alternatively, you can subscribe to receive notifications when a goal makes progress using the channel.goal.progress subscription type. Read more

Authorization

Requires a user OAuth access token with scope set to channel:read:goals. The ID in the broadcaster_id query parameter must match the user ID associated with the user OAuth token. In other words, only the broadcaster can see their goals.

URL

GET https://api.twitch.tv/helix/goals

Required Query Parameters

Parameter	Type	Description
`broadcaster_id`	string	The ID of the broadcaster that created the goals.

Response Fields

Field	Type	Description
`data`	object array	An array of creator goals. The array will contain at most one goal. The array is empty if the broadcaster hasn’t created goals. NOTE: Although the API currently supports only one goal, you should write your application to support one or more goals.
`id`	string	An ID that uniquely identifies this goal.
`broadcaster_id`	string	An ID that uniquely identifies the broadcaster.
`broadcaster_name`	string	The broadcaster’s display name.
`broadcaster_login`	string	The broadcaster’s user handle.
`type`	string	The type of goal. Possible values are: follower — The goal is to increase followers. subscription — The goal is to increase subscriptions. This type shows the net increase or decrease in tier points associated with the subscriptions. subscription_count — The goal is to increase subscriptions. This type shows the net increase or decrease in the number of subscriptions. new_subscription — The goal is to increase subscriptions. This type shows only the net increase in tier points associated with the subscriptions (it does not account for users that unsubscribed since the goal started). new_subscription_count — The goal is to increase subscriptions. This type shows only the net increase in the number of subscriptions (it does not account for users that unsubscribed since the goal started).
`description`	string	A description of the goal, if specified. The description may contain a maximum of 40 characters.
`current_amount`	integer	The goal’s current value. The goal’s `type` determines how this value is increased or decreased. If `type` is follower, this field is set to the broadcaster's current number of followers. This number increases with new followers and decreases when users unfollow the broadcaster. If `type` is subscription, this field is increased and decreased by the points value associated with the subscription tier. For example, if a tier-two subscription is worth 2 points, this field is increased or decreased by 2, not 1. If `type` is subscription_count, this field is increased by 1 for each new subscription and decreased by 1 for each user that unsubscribes. If `type` is new_subscription, this field is increased by the points value associated with the subscription tier. For example, if a tier-two subscription is worth 2 points, this field is increased by 2, not 1. If `type` is new_subscription_count, this field is increased by 1 for each new subscription.
`target_amount`	integer	The goal’s target value. For example, if the broadcaster has 200 followers before creating the goal, and their goal is to double that number, this field is set to 400.
`created_at`	string	The UTC timestamp in RFC 3339 format, which indicates when the broadcaster created the goal.

Response Codes

Code	Meaning
200	Successfully retrieved the broadcaster’s goals.
400	The request was invalid. Make sure the broadcaster’s ID you specified in `broadcaster_id` is correct.
401	The caller failed authentication. Returned if the user is valid but missing the correct scopes, or if the user is valid but the broadcaster ID doesn’t match the user ID in the token.

Example Request

Gets a list of goals that the broadcaster created.

curl -X GET 'https://api.twitch.tv/helix/goals?broadcaster_id=141981764' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' 

# Twitch CLI example that gets broadcaster's goals.

twitch api get /goals -q broadcaster_id=141981764 

Example Response

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

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.
`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.

Rate Limits: Rates are limited per channel based on the account type rather than per access token.

Account type	Limit per minute	Limit per hour
Normal	5	50
Affiliate	10	100
Partner	30	300

The above limits are in addition to the standard Twitch API rate limits. The rate limit headers in the response represent the Twitch rate limits and not the above limits.

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.

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.

Response Codes

Code	Meaning
200	Success.
400	Bad Request.
401	Unauthorized.
403	Forbidden.
404	Message not found or invalid `msg_id`.
429	Too Many Requests. The channel exceeded the number of chat message checks that it may make. See Rate Limits in the endpoint’s description above.
500	Internal Server Error

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?broadcaster_id=12345' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "data": [
    {
      "msg_id": "123",
      "msg_text": "Hello World!"
    },
    {
      "msg_id": "393",
      "msg_text": "Boooooo!"
    }
  ]
}'

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' \
-H 'Content-Type: application/json' \
-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' \
-H 'Content-Type: application/json' \
-d '{
  "user_id": "9327994",
  "msg_id": "836013710",
  "action": "DENY"
}'

Example Response 2

Shows that a message was successfully denied.

204 No Content

Get AutoMod Settings

✎

Gets the broadcaster’s AutoMod settings, which are used to automatically block inappropriate or harassing messages from appearing in the broadcaster’s chat room.

Authorization

Requires a User access token with scope set to moderator:read:automod_settings.

URL

GET https://api.twitch.tv/helix/moderation/automod/settings

Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster whose AutoMod settings you want to get.
moderator_id	Yes	String	The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token. If the broadcaster wants to get their own AutoMod settings (instead of having the moderator do it), set this parameter to the broadcaster’s ID, too.

Response Body

Field	Type	Description
data	object[]	The list of AutoMod settings. The list contains a single object that contains all the AutoMod settings.
aggression	Integer	The Automod level for hostility involving aggression.
broadcaster_id	String	The broadcaster’s ID.
bullying	Integer	The Automod level for hostility involving name calling or insults.
disability	Integer	The Automod level for discrimination against disability.
misogyny	Integer	The Automod level for discrimination against women.
moderator_id	String	The moderator’s ID.
overall_level	Integer	The default AutoMod level for the broadcaster. This field is null if the broadcaster has set one or more of the individual settings.
race_ethnicity_or_religion	Integer	The Automod level for racial discrimination.
sex_based_terms	Integer	The Automod level for sexual content.
sexuality_sex_or_gender	Integer	The AutoMod level for discrimination based on sexuality, sex, or gender.
swearing	Integer	The Automod level for profanity.

Response Codes

Code	Meaning
200	Success.
400	Malformed request.
401	Authentication failure.

Example Request

This example gets the broadcaster’s AutoMod settings.

curl -X GET 'https://api.twitch.tv/helix/moderation/automod/settings?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

This example shows what the response looks like if the broadcaster hasn’t enabled AutoMod.

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "overall_level": null,
      "disability": 0,
      "aggression": 0,
      "sexuality_sex_or_gender": 0,
      "misogyny": 0,
      "bullying": 0,
      "swearing": 0,
      "race_ethnicity_or_religion": 0,
      "sex_based_terms": 0
    }
  ]
}

Update AutoMod Settings

✎

Updates the broadcaster’s AutoMod settings, which are used to automatically block inappropriate or harassing messages from appearing in the broadcaster’s chat room.

Authorization

Requires a User access token with scope set to moderator:manage:automod_settings.

URL

PUT https://api.twitch.tv/helix/moderation/automod/settings

Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster whose AutoMod settings you want to update.
moderator_id	Yes	String	The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token. If the broadcaster wants to update their own AutoMod settings (instead of having the moderator do it), set this parameter to the broadcaster’s ID, too.

Request Body

Because PUT is an overwrite operation, you must include all the fields you want set after the operation completes. Typically, you’ll send a GET request, update the fields you want to change, and pass that object in the PUT request.

You can set either overall_level or the individual settings like aggression, but not both.

Setting overall_level applies default values to the individual settings. However, setting overall_level to 4 does not mean that it applies 4 to all the individual settings. Instead, it applies a set of recommended defaults to the rest of the settings. For example, if you set overall_level to 2, Twitch provides some filtering on discrimination and sexual content, but more filtering on hostility (see the first example response).

If overall_level is currently set and you update swearing to 3, overall_level will be set to null and all settings other than swearing will be set to 0. The same is true if individual settings are set and you update overall_level to 3 — all the individual settings are updated to reflect the default level.

Note that if you set all the individual settings to values that match what overall_level would have set them to, Twitch changes AutoMod to use the default AutoMod level instead of using the individual settings.

Valid values for all levels are from 0 (no filtering) through 4 (most aggressive filtering). These levels affect how aggressively AutoMod holds back messages for moderators to review before they appear in chat or are denied (not shown).

Field	Type	Description
aggression	Integer	The Automod level for hostility involving aggression.
bullying	Integer	The Automod level for hostility involving name calling or insults.
disability	Integer	The Automod level for discrimination against disability.
misogyny	Integer	The Automod level for discrimination against women.
overall_level	Integer	The default AutoMod level for the broadcaster.
race_ethnicity_or_religion	Integer	The Automod level for racial discrimination.
sex_based_terms	Integer	The Automod level for sexual content.
sexuality_sex_or_gender	Integer	The AutoMod level for discrimination based on sexuality, sex, or gender.
swearing	Integer	The Automod level for profanity.

Response Body

Field	Type	Description
data	object[]	The list of AutoMod settings. The list contains a single object that contains all the AutoMod settings.
aggression	Integer	The Automod level for hostility involving aggression.
broadcaster_id	String	The broadcaster’s ID.
bullying	Integer	The Automod level for hostility involving name calling or insults.
disability	Integer	The Automod level for discrimination against disability.
misogyny	Integer	The Automod level for discrimination against women.
moderator_id	String	The moderator’s ID.
overall_level	Integer	The default AutoMod level for the broadcaster. This field is null if the broadcaster has set one or more of the individual settings.
race_ethnicity_or_religion	Integer	The Automod level for racial discrimination.
sex_based_terms	Integer	The Automod level for sexual content.
sexuality_sex_or_gender	Integer	The AutoMod level for discrimination based on sexuality, sex, or gender.
swearing	Integer	The Automod level for profanity.

Response Codes

Code	Meaning
200	Success.
400	Malformed request.
401	Authentication failure.

Example Request 1

This example updates the overall_level setting to 3.

curl -X PUT 'https://api.twitch.tv/helix/moderation/automod/settings?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'
​​-H 'Content-Type: application/json' \
-d '{"overall_level":3}'

Example Response 1

Notice in the response that not all settings are set to level 3.

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "overall_level": 3,
      "disability": 3,
      "aggression": 3,
      "sexuality_sex_or_gender": 3,
      "misogyny": 3,
      "bullying": 2,
      "swearing": 0,
      "race_ethnicity_or_religion": 3,
      "sex_based_terms": 3
    }
  ]
}

If overall_level is set to 3 and you try to change swearing to 2, all other settings are set to 0. If the goal was to change the swearing setting and leave all the others unchanged, the request must have included all the other settings as well.

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "overall_level": null,
      "disability": 0,
      "aggression": 0,
      "sexuality_sex_or_gender": 0,
      "misogyny": 0,
      "bullying": 0,
      "swearing": 2,
      "race_ethnicity_or_religion": 0,
      "sex_based_terms": 0
    }
  ]
}

Get Banned Users

✎

Returns all banned and timed-out users for 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	Type	Description
`broadcaster_id`	string	Provided `broadcaster_id` must match the `user_id` in the OAuth token.

Optional Query Parameters

Parameter	Type	Description
`user_id`	string	Filters the results and only returns a status object for users who are banned in the channel and have a matching user_id. Multiple user IDs can be provided, e.g. `/moderation/banned?broadcaster_id=1&user_id=2&user_id=3` Maximum: 100.
`first`	string	Maximum number of objects to return. Maximum: 100. Default: 1.
`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.
`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 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 the banned user.
`user_login`	string	Login of the banned user.
`user_name`	string	Display name of the banned user.
`expires_at`	string	The UTC date and time (in RFC3999 format) when the timeout expires, or an empty string if the user is permanently banned.
`created_at`	string	The UTC date and time (in RFC3999 format) when the ban was created.
`reason`	string	The reason for the ban if provided by the moderator.
`moderator_id`	string	User ID of the moderator who initiated the ban.
`moderator_login`	string	Login of the moderator who initiated the ban.
`moderator_name`	string	Display name of the moderator who initiated the ban.
`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

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": "2022-03-15T02:00:28Z",
      "created_at": "2022-03-15T01:30:28Z",
      "reason": "Does not like pineapple on pizza.",
      "moderator_id": "141981764",
      "moderator_login": "twitchdev",
      "moderator_name": "TwitchDev"
    },
    {
      "user_id": "424596340",
      "user_login": "quotrok",
      "user_name": "quotrok",
      "expires_at": "2022-08-07T02:07:55Z",
      "created_at": "2022-08-07T02:02:55Z",
      "reason": "Inappropriate words.",
      "moderator_id": "141981764",
      "moderator_login": "twitchdev",
      "moderator_name": "TwitchDev"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
  }
}

Ban User

✎

Bans a user from participating in a broadcaster’s chat room, or puts them in a timeout. For more information about banning or putting users in a timeout, see Ban a User and Timeout a User.

If the user is currently in a timeout, you can call this endpoint to change the duration of the timeout or ban them altogether. If the user is currently banned, you cannot call this method to put them in a timeout instead.

To remove a ban or end a timeout, see Unban user.

Authentication

Requires a User access token with scope set to moderator:manage:banned_users.

URL

POST https://api.twitch.tv/helix/moderation/bans

Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster whose chat room the user is being banned from.
moderator_id	Yes	String	The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token. If the broadcaster wants to ban the user (instead of having the moderator do it), set this parameter to the broadcaster’s ID, too.

Request Body

Field	Required	Type	Description
data	Yes	Object	The user to ban or put in a timeout.
duration	No	Integer	To ban a user indefinitely, don’t include this field. To put a user in a timeout, include this field and specify the timeout period, in seconds. The minimum timeout is 1 second and the maximum is 1,209,600 seconds (2 weeks). To end a user’s timeout early, set this field to 1, or send an Unban user request.
reason	Yes	String	The reason the user is being banned or put in a timeout. The text is user defined and limited to a maximum of 500 characters.
user_id	Yes	String	The ID of the user to ban or put in a timeout.

Response Body

Field	Type	Description
data	Object array	A list that contains the user you successfully banned or put in a timeout.
broadcaster_id	String	The broadcaster whose chat room the user was banned from chatting in.
created_at	string	The UTC date and time (in RFC3999 format) when the ban was created.
end_time	String	The UTC date and time (in RFC3339 format) that the timeout will end. Is null if the user was banned instead of put in a timeout.
moderator_id	String	The moderator that banned or put the user in the timeout.
user_id	String	The user that was banned or was put in a timeout.

Response Codes

Code	Meaning
200	Success
400	Bad Request
401	Unauthorized
403	Forbidden
409	Conflict. You may not update the user’s ban state while someone else is updating the state. For example, someone else is currently banning the user or putting them in a timeout, moving the user from a timeout to a ban, or removing the user from a ban or timeout. Please retry your request.
429	Too Many Requests. It is possible for too many ban requests to occur even within normal Twitch API rate limits.
500	Internal Server Error

Example Request 1

This example bans a user (it doesn’t include the duration field).

curl -X POST 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"data": {"user_id":"9876","reason":"no reason"}}'

Example Response 1

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "user_id": "9876",
      "created_at": "2021-09-28T18:22:31Z",
      "end_time": null
    }
  ]
}

Example Request 2

This example puts a user in a 5 minute timeout.

curl -X POST 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"data": {"user_id":"9876","duration":300,"reason":"no reason"}}'

Example Response 2

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "user_id": "9876",
      "created_at": "2021-09-28T19:27:31Z",
      "end_time": "2021-09-28T19:22:31Z"
    }
  ]
}

Example Request 3

This example shows what happens if you try to place a banned user in a timeout. You can ban a user that’s already in a timeout but you can’t move a banned user into a timeout. To do this, you’d have to remove the ban and then place them in a timeout.

You’ll get the same response if you try to ban a user who is already banned.

curl -X POST 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"data": {"user_id":"9876","duration":300,"reason":"no reason"}}'

Example Response 3

{ 
  "error": "Bad Request", 
  "status": 400, 
  "message": "user is already banned" 
}

Unban User

✎

Removes the ban or timeout that was placed on the specified user (see Ban user).

Authentication

Requires a User access token with scope set to moderator:manage:banned_users.

URL

DELETE https://api.twitch.tv/helix/moderation/bans

Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster whose chat room the user is banned from chatting in.
moderator_id	Yes	String	The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token. If the broadcaster wants to remove the ban (instead of having the moderator do it), set this parameter to the broadcaster’s ID, too.
user_id	Yes	String	The ID of the user to remove the ban or timeout from.

Response Body

If the request succeeds, the status code is 204 No Content.

Response Codes

Code	Meaning
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
409	Conflict. You may not update the user’s ban state while someone else is updating the state. For example, someone else is currently removing the ban or timeout, or they’re moving the user from a timeout to a ban. Please retry your request.
429	Too Many Requests. It is possible for too many unban requests to occur even within normal Twitch API rate limits.
500	Internal Server Error

Example Request 1

This example removes a ban or timeout from a user.

curl -X DELETE 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678&user_id=9876' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response 1

204 No Content

Example Request 2

This example tries to remove a ban or timeout from a user that is not currently banned or in a timeout.

curl -X DELETE 'https://api.twitch.tv/helix/moderation/bans?broadcaster_id=1234&moderator_id=5678&user_id=5432' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response 2

{ 
  "error": "Bad Request", 
  "status": 400, 
  "message": "user is not banned" 
}

Get Blocked Terms

✎

Gets the broadcaster’s list of non-private, blocked words or phrases. These are the terms that the broadcaster or moderator added manually, or that were denied by AutoMod.

Authorization

Requires a User access token with scope set to moderator:read:blocked_terms.

URL

GET https://api.twitch.tv/helix/moderation/blocked_terms

Query Parameters

Parameter	Required	Type	Description
after	No	String	The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value.
broadcaster_id	Yes	String	The ID of the broadcaster whose blocked terms you’re getting.
first	No	Integer	The maximum number of blocked terms to return per page in the response. The minimum page size is 1 blocked term per page and the maximum is 100. The default is 20.
moderator_id	Yes	String	The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token. If the broadcaster wants to get their own block terms (instead of having the moderator do it), set this parameter to the broadcaster’s ID, too.

Response Body

Field	Type	Description
data	object array	The list of blocked terms. The list is in descending order of when they were created (see the `created_at` timestamp).
broadcaster_id	String	The broadcaster that owns the list of blocked terms.
created_at	String	The UTC date and time (in RFC3339 format) of when the term was blocked.
expires_at	String	The UTC date and time (in RFC3339 format) of when the blocked term is set to expire. After the block expires, user’s will be able to use the term in the broadcaster’s chat room. This field is null if the term was added manually or was permanently blocked by AutoMod.
id	String	An ID that uniquely identifies this blocked term.
moderator_id	String	The moderator that blocked the word or phrase from being used in the broadcaster’s chat room.
text	String	The blocked word or phrase.
updated_at	String	The UTC date and time (in RFC3339 format) of when the term was updated. When the term is added, this timestamp is the same as created_at. The timestamp changes as AutoMod continues to deny the term.
pagination	object	The information used to paginate the response data.
cursor	String	The cursor used to page results. Used to set the request’s after query parameter.

Response Codes

Code	Meaning
200	Success.
400	Malformed request.
401	Authentication failure.

Example Request 1

This example gets the last 10 blocked terms (see the first query parameter) that were added.

curl -X GET 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678&first=10' \
-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response 1

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "id": "520e4d4e-0cda-49c7-821e-e5ef4f88c2f2",
      "text": "A phrase I’m not fond of",
      "created_at": "2021-09-29T19:45:37Z",
      "updated_at": "2021-09-29T19:45:37Z",
      "expires_at": null
    },

    . . .

  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6I..."
  }
}

Example Request 2

This example gets the next page of blocked terms. By default, the response includes 20 terms per page. To change the number of items per page, include the first query parameter.

curl -X GET 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678&after=eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6I...' \
-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' 

Add Blocked Term

✎

Adds a word or phrase to the broadcaster’s list of blocked terms. These are the terms that broadcasters don’t want used in their chat room.

Authentication

Requires a User access token with scope set to moderator:manage:blocked_terms.

URL

POST https://api.twitch.tv/helix/moderation/blocked_terms

Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster that owns the list of blocked terms.
moderator_id	Yes	String	The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token. If the broadcaster wants to add the blocked term (instead of having the moderator do it), set this parameter to the broadcaster’s ID, too.

Request Body

Field	Required	Type	Description
text	Yes	String	The word or phrase to block from being used in the broadcaster’s chat room. The term must contain a minimum of 2 characters and may contain up to a maximum of 500 characters. Terms can use a wildcard character (). The wildcard character must appear at the beginning or end of a word, or set of characters. For example, foo or foo*.

Response Body

Field	Type	Description
data	object array	The list of blocked terms. The list will contain the single blocked term that the broadcaster added.
broadcaster_id	String	The broadcaster that owns the list of blocked terms.
created_at	String	The UTC date and time (in RFC3339 format) of when the term was blocked.
expires_at	String	Is set to null.
id	String	An ID that uniquely identifies this blocked term.
moderator_id	String	The moderator that blocked the word or phrase from being used in the broadcaster’s chat room.
text	String	The blocked word or phrase.
updated_at	String	The UTC date and time (in RFC3339 format) of when the term was updated. This timestamp is the same as created_at.

Example Request 1

This example adds a blocked term. Trying to add the same term again will return the previously added term.

curl -X POST 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 789nj68b49pwqs9nh2y2jrlgzju3f' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"text":"A phrase I’m not fond of"}'

Example Response 1

{
  "data": [
    {
      "broadcaster_id": "713936733",
      "moderator_id": "713936733",
      "id": "3bb6e5d3-afb1-416c-ad4e-21af970ccfe7",
      "text": "A phrase I’m not fond of",
      "created_at": "2021-09-29T15:36:45Z",
      "updated_at": "2021-09-29T15:36:45Z",
      "expires_at": null
    }
  ]
}

Example Request 2

This example adds a term that uses the wildcard character (*).

curl -X POST 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678' \
-H 'Authorization: Bearer 789nj68b49pwqs9nh2y2jrlgzju3f' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"text":"crac*"}'

Example Response 2

{
  "data": [
    {
      "broadcaster_id": "1234",
      "moderator_id": "5678",
      "id": "520e4d4e-0cda-49c7-821e-e5ef4f88c2f2",
      "text": "crac*",
      "created_at": "2021-09-29T19:45:37Z",
      "updated_at": "2021-09-29T19:45:37Z",
      "expires_at": null
    }
  ]
}

Remove Blocked Term

✎

Removes the word or phrase that the broadcaster is blocking users from using in their chat room.

Authentication

Requires a User access token with scope set to moderator:manage:blocked_terms.

URL

DELETE https://api.twitch.tv/helix/moderation/blocked_terms

Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster that owns the list of blocked terms.
id	Yes	String	The ID of the blocked term you want to delete.
moderator_id	Yes	String	The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token.

Response Body

If the request succeeds, the status code is 204 No Content.

Example Request

This example deletes a blocked term.

curl -X DELETE 'https://api.twitch.tv/helix/moderation/blocked_terms?broadcaster_id=1234&moderator_id=5678&id=c9fc79b8-0f63-4ef7-9d38-efd811e74ac2' \ 
-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

204 No Content

Delete Chat Messages

✎

NEW Removes a single chat message or all chat messages from the broadcaster’s chat room.

Authentication

Requires a user access token that includes the moderator:manage:chat_messages scope. The ID in the moderator_id query parameter must match the user ID in the access token.

URL

DELETE https://api.twitch.tv/helix/moderation/chat

Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that owns the chat room to remove messages from.
moderator_id	String	Yes	The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the OAuth token. If the broadcaster wants to remove messages themselves, set this parameter to the broadcaster’s ID, too.
message_id	String	No	The ID of the message to remove. The `id` tag in the `PRIVMSG` contains the message’s ID (see PRIVMSG Tags). Restrictions: The message must have been created within the last 6 hours. The message must not belong to the broadcaster. The message must not belong to another moderator. If not specified, the request removes all messages in the broadcaster’s chat room.

Response Body

None

Response Codes

Code	Description
204 No Content	Successfully removed the specified messages.
400 Bad Request	Possible reasons: You may not delete another moderator's messages. You may not delete the broadcaster's messages.
401 Unauthorized	Possible reasons: The Authorization header is required and must contain a user access token. The user access token is missing the moderator:manage:chat_messages scope. The OAuth token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
403 Forbidden	Possible reasons: The user is not one of the broadcaster's moderators.
404 Not Found	Possible reasons: The ID in message_id was not found. The specified message was created more than 6 hours ago.

Example Request

Removes all messages from the broadcaster’s chat room (doesn’t include the message_id query parameter).

curl -X DELETE 'https://api.twitch.tv/helix/moderation/chat?broadcaster_id=11111&moderator_id=44444' \
-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Removes the specified message from the broadcaster’s chat room.

curl -X DELETE 'https://api.twitch.tv/helix/moderation/chat?broadcaster_id=11111&moderator_id=44444&message_id=abc-123-def' \ 
-H 'Authorization: Bearer f4otqljtpbpg24v41v9gechs4yvwy' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

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

Requires a user access token that includes the moderation:read scope. If your app also adds and removes moderators, you can use the channel:manage:moderators scope instead. The ID in the broadcaster_id query parameter must match the user ID in the access token.

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=3` Maximum: 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"
  }
}

Add Channel Moderator

✎

NEW Adds a moderator to the broadcaster’s chat room.

Rate Limits: The channel may add a maximum of 10 moderators within a 10 seconds period.

Authorization

Requires a user access token that includes the channel:manage:moderators scope. The ID in the broadcaster_id query parameter must match the user ID in the access token.

URL

POST https://api.twitch.tv/helix/moderation/moderators

Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that owns the chat room.
user_id	String	Yes	The ID of the user to add as a moderator in the broadcaster’s chat room.

Response Body

None

Response Codes

Code	Meaning
204 No Content	Successfully added the moderator.
400 Bad Request	Possible reasons: The ID in broadcaster_id was not found. The ID in user_id was not found. The user in user_id is already a moderator in the broadcaster's chat room. The user in user_id may not be a moderator because they're banned from the channel.
401 Unauthorized	Possible reasons: The Authorization header is required and must contain a user access token. The user access token is missing the channel:manage:moderators scope. The OAuth token is not valid. The ID in the broadcaster_id query parameter must match the user ID in the access token. The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
422 Unprocessable Entity	The user in user_id is a VIP. To make them a moderator, you must first remove them as a VIP (see Remove Channel VIP).
429 Too Many Requests	The channel has exceeded the number of add-moderator requests they may make within a 10 seconds period. See Rate Limits for this endpoint above.

Example Request

Adds a moderator to the broadcaster’s chat room.

curl -X POST 'https://api.twitch.tv/helix/moderation/moderators?broadcaster_id=11111&user_id=44444' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Remove Channel Moderator

✎

NEW Removes a moderator from the broadcaster’s chat room.

Rate Limits: The channel may remove a maximum of 10 moderators within a 10 seconds period.

Authorization

Requires a user access token that includes the channel:manage:moderators scope. The ID in the broadcaster_id query parameter must match the user ID in the access token.

URL

DELETE https://api.twitch.tv/helix/moderation/moderators

Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that owns the chat room.
user_id	String	Yes	The ID of the user to remove as a moderator from the broadcaster’s chat room.

Response Codes

Code	Meaning
204 No Content	Successfully removed the moderator.
400 Bad Request	Possible reasons: The ID in broadcaster_id was not found. The ID in user_id was not found. The user in user_id is not a moderator in the broadcaster's chat room.
401 Unauthorized	Possible reasons: The Authorization header is required and must contain a user access token. The user access token is missing the channel:manage:moderators scope. The OAuth token is not valid. The ID in the broadcaster_id query parameter must match the user ID in the access token. The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
429 Too Many Requests	The channel has exceeded the number of remove-moderator requests they may make within a 10 seconds period. See Rate Limits for this endpoint above.

Example Request

Removes a moderator from the broadcaster’s chat room.

curl -X DELETE 'https://api.twitch.tv/helix/moderation/moderators?broadcaster_id=11111&user_id=44444' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Get VIPs

✎

NEW Gets a list of the channel’s VIPs.

Authorization

Requires a user access token that includes the channel:read:vips scope. If your app also adds and removes VIP status, you can use the channel:manage:vips scope instead. The ID in the broadcaster_id query parameter must match the user ID in the access token.

URL

GET https://api.twitch.tv/helix/channels/vips

Query Parameters

Parameter	Type	Required?	Description
user_id	String	No	Filters the list for specific VIPs. To specify more than one user, include the user_id parameter for each user to get. For example, `&user_id=1234&user_id=5678`. The maximum number of IDs that you may specify is 100. Ignores those users in the list that aren’t VIPs.
broadcaster_id	String	Yes	The ID of the broadcaster whose list of VIPs you want to get.
first	Integer	No	The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100. The default is 20.
after	String	No	The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read more.

Response Body

Field	Type	Description
data	Object[]	The list of VIPs. The list is empty if the channel doesn’t have VIP users. The list does not include the broadcaster.
user_id	String	An ID that uniquely identifies the VIP user.
user_name	String	The user’s display name.
user_login	String	The user’s login name.
pagination	Object	Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read more.
cursor	String	The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code	Meaning
204 No Content	Successfully retrieved the broadcaster’s list of VIPs.
400 Bad Request	Possible reasons: The broadcaster_id query parameter is required. The number of user_id query parameters exceeds the maximum allowed.
401 Unauthorized	Possible reasons: The Authorization header is required and must contain a user access token. The user access token is missing the channel:read:vips scope. The OAuth token is not valid. The ID in the broadcaster_id query parameter must match the user ID in the access token. The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.

Example Request

Gets a list of the broadcaster’s VIPs

curl -X GET 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Gets a filtered list of the broadcaster’s VIPs. The list in the response contains only those users that are VIPs.

curl -X GET 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123&user_id=456&user_id=678' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Example Request

{
  "data": [
    {
      "user_id": "11111",
      "user_name": "UserDisplayName",
      "user_login": "userloginname"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"
  }
}

Add Channel VIP

✎

NEW Adds a VIP to the broadcaster’s chat room.

Rate Limits: The channel may add a maximum of 10 VIPs within a 10 seconds period.

Authorization

Requires a user access token that includes the channel:manage:vips scope. The ID in the broadcaster_id query parameter must match the user ID in the access token.

URL

POST https://api.twitch.tv/helix/channels/vips

Query Parameters

Parameter	Type	Required?	Description
user_id	String	Yes	The ID of the user to add as a VIP in the broadcaster’s chat room.
broadcaster_id	String	Yes	The ID of the broadcaster that’s granting VIP status to the user.

Response Body

None

Response Codes

Code	Meaning
204 No Content	Successfully added the VIP.
400 Bad Request	Possible reasons: The user in the user_id query parameter is blocked from the broadcaster's channel. The ID in the user_id query parameter is not valid.
401 Unauthorized	Possible reasons: The Authorization header is required and must contain a user access token. The user access token is missing the channel:manage:vips scope. The OAuth token is not valid. The ID in the broadcaster_id query parameter must match the user ID in the access token. The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
409 Conflict	The broadcaster doesn’t have available VIP slots. Read more
422 Unprocessable Entity	Possible reasons: The user in user_id is a moderator. To make them a VIP, you must first remove them as a moderator (see Remove Channel Moderator). The user in the user_id query parameter is already a VIP.
425 Too Early	The broadcaster must complete the Build a Community requirement before they may assign VIPs.
429 Too Many Requests	The channel has exceeded the number of grant-VIP requests they may make within a 10 seconds period. See Rate Limits for this endpoint above.

Example Request

Adds a VIP to the broadcaster’s chat room.

curl -X POST 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123&user_id=456' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Remove Channel VIP

✎

NEW Removes a VIP from the broadcaster’s chat room.

Rate Limits: The channel may remove a maximum of 10 VIPs within a 10 seconds period.

Authorization

Requires a user access token that includes the channel:manage:vips scope. The ID in the broadcaster_id query parameter must match the user ID in the access token.

URL

DELETE https://api.twitch.tv/helix/channels/vips

Query Parameters

Parameter	Type	Required?	Description
user_id	String	Yes	The ID of the user to remove as a VIP from the broadcaster’s chat room.
broadcaster_id	String	Yes	The ID of the broadcaster that’s removing VIP status from the user.

Response Body

None

Response Codes

Code	Meaning
204 No Content	Successfully removed the VIP.
400 Bad Request	Possible reasons: The ID in broadcaster_id is not valid. The ID in user_id is not valid.
401 Unauthorized	Possible reasons: The Authorization header is required and must contain a user access token. The user access token is missing the channel:manage:vips scope. The OAuth token is not valid. The ID in the broadcaster_id query parameter must match the user ID in the access token. The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
422 Unprocessable Entity	The user in user_id is not a VIP.
429 Too Many Requests	The channel has exceeded the number of remove-vip requests they may make within a 10 seconds period. See Rate Limits for this endpoint above.

Example Request

Removes the VIP from the broadcaster’s chat room.

curl -X DELETE 'https://api.twitch.tv/helix/channels/vips?broadcaster_id=123&user_id=456' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Get Polls

✎

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

✎

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
`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	Not used; will be set to 0.
`bits_voting_enabled`	boolean	Not used; will be set to false.
`bits_per_vote`	integer	Not used; will be set to 0.
`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

✎

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 Parameters

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

✎

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 users 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.user_id`	string	ID of the user.
`outcome.top_predictors.user.user_name`	string	Display name of the user.
`outcome.top_predictors.user.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. If the number of outcomes is two, the color is BLUE for the first one and PINK for the second one. If there are more than two outcomes, the color is BLUE for all of them.
`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

✎

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[]	The list of possible outcomes for the Prediction. The minimum number of outcomes that you may specify is 2 and the maximum is 10.
`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. If the number of outcomes is two, the color is BLUE for the first one and PINK for the second one. If there are more than two outcomes, the color is BLUE for all of them.
`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.
429	Too many requests.

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

✎

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 Parameters

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. If the number of outcomes is two, the color is BLUE for the first one and PINK for the second one. If there are more than two outcomes, the color is BLUE for all of them.
`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"
    }
  ]
}

Start a raid

✎

NEW Raid another channel by sending the broadcaster’s viewers to the targeted channel.

When you call the API from a chat bot or extension, the Twitch UX pops up a window at the top of the chat room that identifies the number of viewers in the raid. The raid occurs when the broadcaster clicks Raid Now or after the 90 second countdown expires.

To cancel a pending raid, call Cancel a raid.

To determine whether the raid successfully occurred, you must subscribe to the Channel Raid event. For more information, see Get notified when a raid begins.

Rate Limit: The limit is 10 requests within a 10-minute window.

Authorization

Requires a user access token that includes the channel:manage:raids scope. The ID in the from_broadcaster_id query parameter must match the user ID in the OAuth token.

URL

POST https://api.twitch.tv/helix/raids

Required Request Parameters

Parameter	Type	Description
`from_broadcaster_id`	string	The ID of the broadcaster that’s sending the raiding party.
`to_broadcaster_id`	string	The ID of the broadcaster to raid.

Response Body

Field	Type	Description
`data`	Object[]	A list of raids. The list will contain the single raid that this request created.
`created_at`	String	The UTC date and time, in RFC3339 format, when the raid request was created.
`is_mature`	Boolean	A Boolean value that indicates whether the channel being raided contains mature content.

Response Codes

Code	Meaning
200 OK	The request to start the raid was successful. To determine whether the raid successfully occurred (the broadcaster clicked Raid Now or the countdown expired), you must subscribe to the Channel Raid event.
400 Bad Request	Possible reasons: The raiding broadcaster is blocked from the targeted channel. The targeted channel doesn't accept raids from this broadcaster. There are too many viewers in the raiding party. The IDs in from_broadcaster_id and to_broadcaster_id cannot be the same ID. The ID in the from_broadcaster_id query parameter is not valid. It must be a positive integer. The ID in the to_broadcaster_id query parameter is not valid. It must be a positive integer.
401 Unauthorized	Possible reasons: The token expired or was revoked. The OAuth token doesn't include the required scope. The ID in the from_broadcaster_id query parameter doesn't match the user ID in the OAuth token. The request didn't specify the Authorization header. The request didn't specify the Client-Id header. The ID in the Client-Id header doesn't match the Client ID in the OAuth token.
404 Not Found	Possible reasons: The targeted channel was not found.
409 Conflict	Possible reasons: The broadcaster is already in the process of raiding another channel.
429 Too Many Requests	Possible reasons: The broadcaster exceeded the number of raid requests that they may make. The limit is 10 requests within a 10-minute window.

Example Request

curl -X POST 'https://api.twitch.tv/helix/raids?from_broadcaster_id=12345678&to_broadcaster_id=87654321' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Example Response

{
  "data": [
    {
      "created_at": "2022-02-18T07:20:50.52Z",
      "is_mature": false
    }
  ]
}

Cancel a raid

✎

NEW Cancel a pending raid.

You can cancel a raid at any point up until the broadcaster clicks Raid Now in the Twitch UX or the 90 seconds countdown expires.

Rate Limit: The limit is 10 requests within a 10-minute window.

Authorization

Requires a user access token that includes the channel:manage:raids scope. The ID in the broadcaster_id query parameter must match the user ID in the OAuth token.

URL

DELETE https://api.twitch.tv/helix/raids

Required Request Parameters

Parameter	Type	Description
`broadcaster_id`	string	The ID of the broadcaster that sent the raiding party.

Response Body

None

Response Codes

Code	Meaning
204 No Content	The pending raid was successfully canceled.
400 Bad Request	Possible reasons: The ID in the broadcaster_id query parameter is not valid. It must be a positive integer.
401 Unauthorized	Possible reasons: The token expired or was revoked. The OAuth token doesn't include the required scope. The ID in the broadcaster_id query parameter doesn't match the user ID in the OAuth token. The request didn't specify the Authorization header. The request didn't specify the Client-Id header. The ID in the Client-Id header doesn't match the Client ID in the OAuth token.
404 Not Found	Possible reasons: The broadcaster doesn't have a pending raid to cancel.
429 Too Many Requests	Possible reasons: The broadcaster exceeded the number of raid requests that they may make. The limit is 10 requests within a 10-minute window.

Example Request

curl -X DELETE 'https://api.twitch.tv/helix/raids?broadcaster_id=12345678' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Get Channel Stream Schedule

✎

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. 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.
`segment.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

✎

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

✎

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

✎

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. To create a non-recurring segment, the broadcaster must be a partner or affiliate.

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.
`segment.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' \
-H 'Content-Type: application/json' \
-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

✎

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'
-H 'Content-Type: application/json' \
-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

✎

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	A URL to a thumbnail of the channel’s profile 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 Soundtrack Current Track

✎

BETA Gets the Soundtrack track that the broadcaster is playing.

Authorization

Requires an App access token or User access token.

URL

GET https://api.twitch.tv/helix/soundtrack/current_track

Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster that’s playing a Soundtrack track.

Response Body

Field	Type	Description
data	SoundtrackCurrentTrack[]	A list that contains the Soundtrack track that the broadcaster is playing.
track	SoundtrackTrack	The track that’s currently playing.
album	SoundtrackAlbum	The album that includes the track.
id	String	The album’s ASIN (Amazon Standard Identification Number).
image_url	String	A URL to the album’s cover art.
name	String	The album’s name. If the album contains explicit content, the name will contain [Explicit] in the string. For example, Let It Die [Explicit].
artists	SoundtrackArtist[]	The artists included on the track.
creator_channel_id	String	The ID of the Twitch user that created the track. Is empty if a Twitch user didn’t create the track.
id	String	The artist’s ASIN (Amazon Standard Identification Number).
name	String	The artist’s name. This can be the band’s name or the solo artist’s name.
duration	Integer	The duration of the track, in seconds.
id	String	The track’s ASIN (Amazon Standard Identification Number).
isrc	String	The track’s ISRC (International Standard Recording Code).
title	String	The track’s title. If the track contains explicit content, the title will contain [Explicit] in the string. For example, Let It Die [Explicit].
source	SoundtrackSource	The source of the track that’s currently playing. For example, a playlist or station.
content_type	String	The type of content that `id` maps to. Possible values are: PLAYLIST STATION
id	String	The playlist’s or station’s ASIN (Amazon Standard Identification Number).
image_url	String	A URL to the playlist’s or station’s image art.
soundtrack_url	String	A URL to the playlist on Soundtrack. The string is empty if `content-type` is STATION.
spotify_url	String	A URL to the playlist on Spotify. The string is empty if `content-type` is STATION.
title	String	The playlist’s or station’s title.

Response Codes

Code	Meaning
200	Success
400	Malformed request
401	Unauthorized
404	The broadcaster is not playing a track.
500	Internal server error

Example Request

curl -X GET 'https://api.twitch.tv/helix/soundtrack/current_track?broadcaster_id=1234' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

{
  "data": [
    {
      "track": {
        "artists": [
          {
            "id": "B07S7JG3TK",
            "name": "Enoth",
            "creator_channel_id": "39051113"
          }
        ],
        "id": "B08D6QFS38",
        "isrc": "CCXXXYYNNNNN",
        "duration": 153,
        "title": "Please stay",
        "album": {
          "id": "B08D6PMKYL",
          "name": "Summer 2020",
          "image_url": "https://m.media-amazon.com/images/I/51zs1JZY8tL.jpg"
        }
      },
      "source": {
        "id": "B08HCW84SF",
        "content_type": "PLAYLIST",
        "title": "Beats To Stream To",
        "image_url": "https://m.media-amazon.com/images/I/419WuvMXzEL.jpg",
        "soundtrack_url": "https://soundtrack.twitch.tv/playlist?playlistID=B08HCW84SF",
        "spotify_url": "https://open.spotify.com/playlist/1LOP14236oTUscowY3NvYN"
      }
    }
  ]
}

Get Soundtrack Playlist

✎

BETA Gets the tracks of a Soundtrack playlist.

Authorization

Requires an App access token or User access token.

URL

GET https://api.twitch.tv/helix/soundtrack/playlist

Query Parameters

Parameter	Required	Type	Description
id	Yes	String	The ID of the Soundtrack playlist to get.
first	No	Integer	The maximum number of tracks to return for this playlist in the response. The minimum number of tracks is 1 and the maximum is 50. The default is 20.
after	No	String	The cursor used to get the next page of tracks for this playlist. The Pagination object in the response contains the cursor’s value.

Response Body

Field	Type	Description
data	SoundtrackTrack[]	The list of tracks in the playlist.
album	SoundtrackAlbum	The album that includes the track.
id	String	The album’s ASIN (Amazon Standard Identification Number).
image_url	String	A URL to the album’s cover art.
name	String	The album’s name. If the album contains explicit content, the name will contain [Explicit] in the string. For example, Let It Die [Explicit].
artists	SoundtrackArtist[]	The artists included on the track.
creator_channel_id	String	The ID of the Twitch user that created the track. Is empty if a Twitch user didn’t create the track.
id	String	The artist’s ASIN (Amazon Standard Identification Number).
name	String	The artist’s name. This can be the band’s name or the solo artist’s name.
duration	Integer	The duration of the track, in seconds.
id	String	The track’s ASIN (Amazon Standard Identification Number).
isrc	String	The track’s ISRC (International Standard Recording Code).
title	String	The track’s title. If the track contains explicit content, the title will contain [Explicit] in the string. For example, Let It Die [Explicit].
pagination	Pagination	Contains the information used to page through a list of tracks. The object is empty if there are no more tracks to page through.
cursor	String	The cursor to set the after query parameter to to get the next page of tracks.

Response Codes

Code	Meaning
200	Success
400	Malformed request
401	Unauthorized
404	Not found
500	Internal server error

Example Request

curl -X GET 'https://api.twitch.tv/helix/soundtrack/playlist?id=B0912YMKSL' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

{
  "data": [
    {
      "artists": [
        {
          "id": "B002F8OLPK",
          "name": "BJ The Chicago Kid",
          "creator_channel_id": ""
        }
      ],
      "id": "B09J7FZ92D",
      "isrc": "QM24S2106597",
      "duration": 210,
      "title": "Smooth [Explicit]",
      "album": {
        "id": "B09J7B37VS",
        "name": "Smooth [Explicit]",
        "image_url": "https://m.media-amazon.com/images/I/316SDaD-XQL.jpg"
      }
    },
    {
      "artists": [
        {
          "id": "B071ZL7NDT",
          "name": "23 Unofficial",
          "creator_channel_id": "647990463"
        },
        {
          "id": "B073PHDDSK",
          "name": "KALLITECHNIS",
          "creator_channel_id": ""
        }
      ],
      "id": "B09C8344GZ",
      "isrc": "QM24S2105530",
      "duration": 154,
      "title": "OUTTA MY WAY",
      "album": {
        "id": "B09C794J2L",
        "name": "OUTTA MY WAY",
        "image_url": "https://m.media-amazon.com/images/I/515HYAEtpeL.jpg"
      }
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6MjB9fQ"
  }
}

Get Soundtrack Playlists

✎

BETA Gets a list of Soundtrack playlists.

The list contains information about the playlists, such as their titles and descriptions. To get a playlist’s tracks, call Get Soundtrack Playlist and specify the playlist’s ID.

Authorization

Requires an App access token or User access token.

URL

GET https://api.twitch.tv/helix/soundtrack/playlists

Query Parameters

Parameter	Required	Type	Description
id	No	String	The ID of the Soundtrack playlist to get. Specify an ID only if you want to get a single playlist instead of all playlists.
first	No	Integer	The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 50 items per page. The default is 20.
after	No	String	The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value. Read more.

Response Body

Field	Type	Description
data	SoundtrackPlaylistMetadata[]	The list of Soundtrack playlists.
description	String	A short description about the music that the playlist includes.
id	String	The playlist’s ASIN (Amazon Standard Identification Number).
image_url	String	A URL to the playlist’s image art. Is empty if the playlist doesn’t include art.
title	String	The playlist’s title.
pagination	Object	Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read more.
cursor	String	The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

Code	Meaning
200	Success
401	Unauthorized
404	Not found
500	Internal server error

Example Request

Gets all playlists.

curl -X GET 'https://api.twitch.tv/helix/soundtrack/playlists' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

{
  "data": [
    {
      "title": "Label Spotlight: Radio Juicy",
      "id": "B08P3N4ZPD",
      "image_url": "https://m.media-amazon.com/images/I/517kGzeaRhL.jpg",
      "description": "Journey through boom-bap, lo-fi, trap and ambient sounds, courtesy of esteemed label Radio Juicy."
    },
    {
      "title": "Fall Days",
      "id": "B09LVX24K7",
      "image_url": "https://m.media-amazon.com/images/I/41w3M-1KfXL.jpg",
      "description": "Turn a new leaf with these chill pop & indie tunes."
    },
    {
      "title": "Release Spotlight: JVNA",
      "id": "B09M7H78YL",
      "image_url": "https://m.media-amazon.com/images/I/419V2D2OlML.jpg",
      "description": "Twitch streamer, singer-songwriter and producer JVNA presents her debut album \"Hope in Chaos\"."
    },
    {
      "title": "Among Us",
      "id": "B08ZDWR371",
      "image_url": "https://m.media-amazon.com/images/I/414O3CYQguL.jpg",
      "description": "Traverse space, do tasks, and eject the Impostors in this official Among Us playlist!"
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6MjB9fQ"
  }
}

Gets a single playlist.

curl -X GET 'https://api.twitch.tv/helix/soundtrack/playlists?id=B0912YMKSL' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Response

{
  "data": [
    {
      "title": "Night Shift",
      "id": "B0912YMKSL",
      "image_url": "https://m.media-amazon.com/images/I/41UoIaB4VaL.jpg",
      "description": "R&B to ride out to."
    }
  ],
  "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/twitchname/manager/highlighter/456?t=0h4m06s"
            },
            ...
          ]
        }
      ]
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjoiMjk1MjA0Mzk3OjI1Mzpib29rbWFyazoxMDZiOGQ1Y"
  }
}

Get Broadcaster Subscriptions

✎

Gets a list of users that subscribe to the specified 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 the list to include only the specified subscribers. To specify more than one subscriber, include this parameter for each subscriber. For example, &user_id=1234&user_id=5678. You may specify a maximum of 100 subscribers.
`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	Is 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 total number of users that subscribe to this broadcaster.
`points`	integer	The current number of subscriber points earned by this broadcaster. Points are based on the subscription tier of each user that subscribes to this broadcaster. For example, a Tier 1 subscription is worth 1 point, Tier 2 is worth 2 points, and Tier 3 is worth 6 points. The number of points determines the number of emote slots that are unlocked for the broadcaster (see Subscriber Emote Slots).

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,
  "points": 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_id`	string	The ID of the user that gifted the subscription to the user. The object includes this field only if `is_gift` is true.
`gifter_login`	string	The gifter’s login name. The object includes this field only if `is_gift` is true.
`gifter_name`	string	The gifter’s display name. The object includes this field only 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": "141981764 does not subscribe to 149747285",
  "status": 404
}

Get All Stream Tags

✎

Gets the list of all stream tags that Twitch defines. You can also filter the list by one or more tag IDs.

For an online list of the possible tags, see List of All Tags.

Authentication

Requires an application OAuth access token.

URL

GET https://api.twitch.tv/helix/tags/streams

Required Query Parameters

None

Optional Query Parameters

Name	Type	Description
`after`	string	The cursor used to get the next page of results. The `pagination` object in the response contains the cursor’s value. The `after` and `tag_id` query parameters are mutually exclusive.
`first`	integer	The maximum number of tags to return per page. Maximum: 100. Default: 20.
`tag_id`	string	An ID that identifies a specific tag to return. Include the query parameter for each tag you want returned. For example, `tag_id=123&tag_id=456`. You may specify a maximum of 100 IDs.

Response Fields

Field	Type	Description
`data`	object array	An array of tag objects.
`tag_id`	string	An ID that identifies the tag.
`is_auto`	Boolean	A Boolean value that determines whether the tag is an automatic tag. An automatic tag is one that Twitch adds to the stream. You cannot add or remove automatic tags. The value is `true` if the tag is an automatic tag; otherwise, `false`.
`localization_names`	map[string,string]	A dictionary that contains the localized names of the tag. The key is in the form, <locale>-<coutry/region>. For example, us-en. The value is the localized name.
`localization_descriptions`	map[string,string]	A dictionary that contains the localized descriptions of the tag. The key is in the form, <locale>-<coutry/region>. For example, us-en. The value is the localized description.
`pagination`	object	An object that contains the cursor used to get the next page of tags.
`cursor`	string	The cursor value that you set the `after` query parameter to.

Example Request

This gets the first page of stream tags that Twitch defines.

curl -X GET 'https://api.twitch.tv/helix/tags/streams' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

# Twitch CLI examples that:

# Gets the first page of stream tags.
twitch api get /tags/streams

# Get the specified stream tags.
twitch api get /tags/streams -q tag_id=39490173-ed5f-4271-96a8-26ab546ee1e9 -q tag_id=233f4789-1ad0-403c-aaf9-7d37a22264e7

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 stream tags that are set on the specified channel.

Authentication

Requires an application OAuth access token.

URL

GET https://api.twitch.tv/helix/streams/tags

Required Query Parameters

Name	Type	Description
`broadcaster_id`	string	The user ID of the channel to get the tags from.

Optional Query Parameters

None

Response Fields

Field	Type	Description
`data`	object array	An array of tag objects.
`tag_id`	string	An ID that identifies the tag.
`is_auto`	Boolean	A Boolean value that determines whether the tag is an automatic tag. An automatic tag is one that Twitch adds to the stream. You cannot add or remove automatic tags. The value is `true` if the tag is an automatic tag; otherwise, `false`.
`localization_names`	map[string,string]	A dictionary that contains the localized names of the tag. The key is in the form, <locale>-<coutry/region>. For example, us-en. The value is the localized name.
`localization_descriptions`	map[string,string]	A dictionary that contains the localized descriptions of the tag. The key is in the form, <locale>-<coutry/region>. For example, us-en. The value is the localized description.
`pagination`	object	An object that contains the cursor used to get the next page of tags.
`cursor`	string	The cursor value that you set the `after` query parameter to.

Example Request

This example gets the tags on the TwitchGaming channel.

curl -X GET
'https://api.twitch.tv/helix/streams/tags?broadcaster_id=527115020' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

# Twitch CLI example that gets the list of tags on the TwitchGaming channel.
twitch api get /streams/tags -q broadcaster_id=527115020

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 one or more tags to the specified channel, overwriting any existing tags. If the request does not specify tags, all existing tags are removed from the channel.

NOTE: You may not specify automatic tags; the call will fail if you specify automatic tags. Automatic tags are tags that Twitch applies to the channel. For a list of automatic tags, see List of All Tags. To get the list programmatically, see Get All Stream Tags.

Tags expire 72 hours after they are applied, unless the channel is live within that time period. If the channel is live within the 72-hour window, the 72-hour clock restarts when the channel goes offline. The expiration period is subject to change.

Authentication

Requires a user OAuth access token with a scope of channel:manage:broadcast.

URL

PUT https://api.twitch.tv/helix/streams/tags

Required Query Parameters

Name	Type	Description
`broadcaster_id`	string	The user ID of the channel to apply the tags to.

Optional Query Parameters

None

Optional Body Parameter

Name	Type	Description
`tag_ids`	string array	A list of IDs that identify the tags to apply to the channel. You may specify a maximum of five tags. To remove all tags from the channel, set `tag_ids` to an empty array.

Example Request

This example applies two stream tags to channel 257788195.

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","52d7e4cc-633d-46f5-818c-bb59102d9549"]}'

# Twitch CLI examples that:

# Adds two stream tags to the channel.
twitch api put /streams/tags -q broadcaster_id=1234567 -b '{"tag_ids":["621fb5bf-5498-4d8f-b4ac-db4d40d401bf", "52d7e4cc-633d-46f5-818c-bb59102d9549"]}'

# Removes all stream tags from the channel.
twitch api put /streams/tags -q broadcaster_id=1234567 -b '{"tag_ids":[]}'

Example Response

The response body is empty.

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:email scope 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. NOTE: This field has been deprecated. For information, see Get Users API endpoint – “view_count” deprecation. The response continues to include the field; however, it contains stale data. You should stop displaying this data at your earliest convenience.
`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:28Z"
    }
  ]
}

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. If only `from_id` was in the request, this is the total number of followed users. If only `to_id` was in the request, this is the total number of followers. If both `from_id` and `to_id` were in the request, this is 1 (if the "from" user follows the "to" user) or 0.

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"
   }
}

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:broadcast or user: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 Fields

Fields	Type	Description
`data`	string[]	An array of IDs of the videos that were deleted.

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"
  ]
}

Send Whisper

✎

NEW Sends a whisper message to the specified user.

NOTE: The user sending the whisper must have a verified phone number (see the Phone Number setting in your Security and Privacy settings).

NOTE: The API may silently drop whispers that it suspects of violating Twitch policies. (The API does not indicate that it dropped the whisper; it returns a 204 status code as if it succeeded).

Rate Limits: You may whisper to a maximum of 40 unique recipients per day. Within the per day limit, you may whisper a maximum of 3 whispers per second and a maximum of 100 whispers per minute.

Authorization

Requires a user access token that includes the user:manage:whispers scope. The ID in the from_user_id query parameter must match the user ID in the access token.

URL

POST https://api.twitch.tv/helix/whispers

Request Query Parameters

Parameter	Type	Required?	Description
from_user_id	String	Yes	The ID of the user sending the whisper. This user must have a verified phone number.
to_user_id	String	Yes	The ID of the user to receive the whisper.

Request Body Parameters

Field	Type	Required?	Description
message	String	Yes	The whisper message to send. The message must not be empty. The maximum message lengths are: 500 characters if the user you're sending the message to hasn't whispered you before. 10,000 characters if the user you're sending the message to has whispered you before. Messages that exceed the maximum length are truncated.

Response Body

None

Response Codes

Code	Meaning
204 No Content	Successfully sent the whisper message or the message was silently dropped.
400 Bad Request	Possible reasons: The ID in the from_user_id and to_user_id query parameters must be different. The `message` field must not contain an empty string. The user that you're sending the whisper to doesn't allow whisper messages (see the Block Whispers from Strangers setting in your Security and Privacy settings). Whisper messages may not be sent to suspended users. The ID in the from_user_id query parameter is not valid. The ID in the to_user_id query parameter is not valid.
401 Unauthorized	Possible reasons: The user in the from_user_id query parameter must have a verified phone number. The Authorization header is required and must contain a user access token. The user access token is missing the user:manage:whispers scope. The OAuth token is not valid. This ID in from_user_id must match the user ID in the user access token. The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
403 Forbidden	Possible reasons: Whisper messages may not be sent from suspended users. The account that's sending the message doesn't allow sending whispers.
404 Not Found	The ID in to_user_id was not found.
429 Too Many Requests	The sending user exceeded the number of whisper requests that they may make. See Rate Limits for this endpoint above.

Example Request

Send the user a whisper message.

curl -X POST 'https://api.twitch.tv/helix/whispers?from_user_id=123&to_user_id=456' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t' \
-H 'Content-Type: application/json' \
-d '{"message":"hello"}'