Twitch API Reference

Resource	Endpoint	Description
Ads	Start Commercial	Starts a commercial on the specified channel.
Ads	Get Ad Schedule	Returns ad schedule related information.
Ads	Snooze Next Ad	Pushes back the timestamp of the upcoming automatic mid-roll ad by 5 minutes.
Analytics	Get Extension Analytics	Gets an analytics report for one or more extensions.
Analytics	Get Game Analytics	Gets an analytics report for one or more games.
Bits	Get Bits Leaderboard	Gets the Bits leaderboard for the authenticated broadcaster.
Bits	Get Cheermotes	Gets a list of Cheermotes that users can use to cheer Bits.
Bits	Get Extension Transactions	Gets an extension’s list of transactions.
Channels	Get Channel Information	Gets information about one or more channels.
Channels	Modify Channel Information	Updates a channel’s properties.
Channels	Get Channel Editors	Gets the broadcaster’s list editors.
Channels	Get Followed Channels	Gets a list of broadcasters that the specified user follows. You can also use this endpoint to see whether a user follows a specific broadcaster.
Channels	Get Channel Followers	Gets a list of users that follow the specified broadcaster. You can also use this endpoint to see whether a specific user follows the broadcaster.
Channel Points	Create Custom Rewards	Creates a Custom Reward in the broadcaster’s channel.
Channel Points	Delete Custom Reward	Deletes a custom reward that the broadcaster created.
Channel Points	Get Custom Reward	Gets a list of custom rewards that the specified broadcaster created.
Channel Points	Get Custom Reward Redemption	Gets a list of redemptions for a custom reward.
Channel Points	Update Custom Reward	Updates a custom reward.
Channel Points	Update Redemption Status	Updates a redemption’s status.
Charity	Get Charity Campaign	Gets information about the broadcaster’s active charity campaign.
Charity	Get Charity Campaign Donations	Gets the list of donations that users have made to the broadcaster’s active charity campaign.
Chat	Get Chatters	Gets the list of users that are connected to the broadcaster’s chat session.
Chat	Get Channel Emotes	Gets the broadcaster’s list of custom emotes.
Chat	Get Global Emotes	Gets all global emotes.
Chat	Get Emote Sets	Gets emotes for one or more specified emote sets.
Chat	Get Channel Chat Badges	Gets the broadcaster’s list of custom chat badges.
Chat	Get Global Chat Badges	Gets Twitch’s list of chat badges.
Chat	Get Chat Settings	Gets the broadcaster’s chat settings.
Chat	Get Shared Chat Session	NEW Retrieves the active shared chat session for a channel.
Chat	Get User Emotes	NEW Retrieves emotes available to the user across all channels.
Chat	Update Chat Settings	Updates the broadcaster’s chat settings.
Chat	Send Chat Announcement	Sends an announcement to the broadcaster’s chat room.
Chat	Send a Shoutout	Sends a Shoutout to the specified broadcaster.
Chat	Send Chat Message	NEW Sends a message to the broadcaster’s chat room.
Chat	Get User Chat Color	Gets the color used for the user’s name in chat.
Chat	Update User Chat Color	Updates the color used for the user’s name in chat.
Clips	Create Clip	Creates a clip from the broadcaster’s stream.
Clips	Get Clips	Gets one or more video clips.
Conduits	Get Conduits	NEW Gets the conduits for a client ID.
Conduits	Create Conduits	NEW Creates a new conduit.
Conduits	Update Conduits	NEW Updates a conduit’s shard count.
Conduits	Delete Conduit	NEW Deletes a specified conduit.
Conduits	Get Conduit Shards	NEW Gets a lists of all shards for a conduit.
Conduits	Update Conduit Shards	NEW Updates shard(s) for a conduit.
CCLs	Get Content Classification Labels	Gets information about Twitch content classification labels.
Entitlements	Get Drops Entitlements	Gets an organization’s list of entitlements that have been granted to a game, a user, or both.
Entitlements	Update Drops Entitlements	Updates the Drop entitlement’s fulfillment status.
Extensions	Get Extension Configuration Segment	Gets the specified configuration segment from the specified extension.
Extensions	Set Extension Configuration Segment	Updates a configuration segment.
Extensions	Set Extension Required Configuration	Updates the extension’s required_configuration string.
Extensions	Send Extension PubSub Message	Sends a message to one or more viewers.
Extensions	Get Extension Live Channels	Gets a list of broadcasters that are streaming live and have installed or activated the extension.
Extensions	Get Extension Secrets	Gets an extension’s list of shared secrets.
Extensions	Create Extension Secret	Creates a shared secret used to sign and verify JWT tokens.
Extensions	Send Extension Chat Message	Sends a message to the specified broadcaster’s chat room.
Extensions	Get Extensions	Gets information about an extension.
Extensions	Get Released Extensions	Gets information about a released extension.
Extensions	Get Extension Bits Products	Gets the list of Bits products that belongs to the extension.
Extensions	Update Extension Bits Product	Adds or updates a Bits product that the extension created.
EventSub	Create EventSub Subscription	Creates an EventSub subscription.
EventSub	Delete EventSub Subscription	Deletes an EventSub subscription.
EventSub	Get EventSub Subscriptions	Gets a list of EventSub subscriptions that the client in the access token created.
Games	Get Top Games	Gets information about all broadcasts on Twitch.
Games	Get Games	Gets information about specified games.
Goals	Get Creator Goals	Gets the broadcaster’s list of active goals.
Guest Star	Get Channel Guest Star Settings	BETA Gets the channel settings for configuration of the Guest Star feature for a particular host.
Guest Star	Update Channel Guest Star Settings	BETA Mutates the channel settings for configuration of the Guest Star feature for a particular host.
Guest Star	Get Guest Star Session	BETA Gets information about an ongoing Guest Star session for a particular channel.
Guest Star	Create Guest Star Session	BETA Programmatically creates a Guest Star session on behalf of the broadcaster.
Guest Star	End Guest Star Session	BETA Programmatically ends a Guest Star session on behalf of the broadcaster.
Guest Star	Get Guest Star Invites	BETA Provides the caller with a list of pending invites to a Guest Star session.
Guest Star	Send Guest Star Invite	BETA Sends an invite to a specified guest on behalf of the broadcaster for a Guest Star session in progress.
Guest Star	Delete Guest Star Invite	BETA Revokes a previously sent invite for a Guest Star session.
Guest Star	Assign Guest Star Slot	BETA Allows a previously invited user to be assigned a slot within the active Guest Star session.
Guest Star	Update Guest Star Slot	BETA Allows a user to update the assigned slot for a particular user within the active Guest Star session.
Guest Star	Delete Guest Star Slot	BETA Allows a caller to remove a slot assignment from a user participating in an active Guest Star session.
Guest Star	Update Guest Star Slot Settings	BETA Allows a user to update slot settings for a particular guest within a Guest Star session.
Hype Train	Get Hype Train Events	Gets information about the broadcaster’s current or most recent Hype Train event.
Moderation	Check AutoMod Status	Checks whether AutoMod would flag the specified message for review.
Moderation	Manage Held AutoMod Messages	Allow or deny the message that AutoMod flagged for review.
Moderation	Get AutoMod Settings	Gets the broadcaster’s AutoMod settings.
Moderation	Update AutoMod Settings	Updates the broadcaster’s AutoMod settings.
Moderation	Get Banned Users	Gets all users that the broadcaster banned or put in a timeout.
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 Unban Requests	NEW Gets a list of unban requests for a broadcaster’s channel.
Moderation	Resolve Unban Requests	NEW Resolves an unban request by approving or denying it.
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 from the broadcaster’s list of blocked terms.
Moderation	Delete Chat Messages	Removes a single chat message or all chat messages from the broadcaster’s chat room.
Moderation	Get Moderated Channels	Gets a list of channels that the specified user has moderator privileges in.
Moderation	Get Moderators	Gets all users allowed to moderate the broadcaster’s chat room.
Moderation	Add Channel Moderator	Adds a moderator to the broadcaster’s chat room.
Moderation	Remove Channel Moderator	Removes a moderator from the broadcaster’s chat room.
Moderation	Get VIPs	Gets a list of the broadcaster’s VIPs.
Moderation	Add Channel VIP	Adds the specified user as a VIP in the broadcaster’s channel.
Moderation	Remove Channel VIP	Removes the specified user as a VIP in the broadcaster’s channel.
Moderation	Update Shield Mode Status	Activates or deactivates the broadcaster’s Shield Mode.
Moderation	Get Shield Mode Status	Gets the broadcaster’s Shield Mode activation status.
Moderation	Warn Chat User	NEW Warns a user in the specified broadcaster’s chat room, preventing them from chat interaction until the warning is acknowledged.
Polls	Get Polls	Gets a list of polls that the broadcaster created.
Polls	Create Poll	Creates a poll that viewers in the broadcaster’s channel can vote on.
Polls	End Poll	End an active poll.
Predictions	Get Predictions	Gets a list of Channel Points Predictions that the broadcaster created.
Predictions	Create Prediction	Create a Channel Points Prediction.
Predictions	End Prediction	Locks, resolves, or cancels a Channel Points Prediction.
Raids	Start a raid	Raid another channel by sending the broadcaster’s viewers to the targeted channel.
Raids	Cancel a raid	Cancel a pending raid.
Schedule	Get Channel Stream Schedule	Gets the broadcaster’s streaming schedule.
Schedule	Get Channel iCalendar	Gets the broadcaster’s streaming schedule as an iCalendar.
Schedule	Update Channel Stream Schedule	Updates the broadcaster’s schedule settings, such as scheduling a vacation.
Schedule	Create Channel Stream Schedule Segment	Adds a single or recurring broadcast to the broadcaster’s streaming schedule.
Schedule	Update Channel Stream Schedule Segment	Updates a scheduled broadcast segment.
Schedule	Delete Channel Stream Schedule Segment	Deletes a broadcast from the broadcaster’s streaming schedule.
Search	Search Categories	Gets the games or categories that match the specified query.
Search	Search Channels	Gets the channels that match the specified query and have streamed content within the past 6 months.
Streams	Get Stream Key	Gets the channel’s stream key.
Streams	Get Streams	Gets a list of all streams.
Streams	Get Followed Streams	Gets the list of broadcasters that the user follows and that are streaming live.
Streams	Create Stream Marker	Adds a marker to a live stream.
Streams	Get Stream Markers	Gets a list of markers from the user’s most recent stream or from the specified VOD/video.
Subscriptions	Get Broadcaster Subscriptions	Gets a list of users that subscribe to the specified broadcaster.
Subscriptions	Check User Subscription	Checks whether the user subscribes to the broadcaster’s 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 the broadcaster or Twitch added to their channel.
Teams	Get Channel Teams	Gets the list of Twitch teams that the broadcaster is a member of.
Teams	Get Teams	Gets information about the specified Twitch team.
Users	Get Users	Gets information about one or more users.
Users	Update User	Updates the user’s information.
Users	Get User Block List	Gets the list of users that the broadcaster has blocked.
Users	Block User	Blocks the specified user from interacting with or having contact with the broadcaster.
Users	Unblock User	Removes the user from the broadcaster’s list of blocked users.
Users	Get User Extensions	Gets a list of all extensions (both active and inactive) that the broadcaster has installed.
Users	Get User Active Extensions	Gets the active extensions that the broadcaster has installed for each configuration.
Users	Update User Extensions	Updates an installed extension’s information.
Videos	Get Videos	Gets information about one or more published videos.
Videos	Delete Videos	Deletes one or more videos.
Whispers	Send Whisper	Sends a whisper message to the specified user.

Start Commercial

✎

Starts a commercial on the specified channel.

NOTE: Only partners and affiliates may run commercials and they must be streaming live at the time.

NOTE: Only the broadcaster may start a commercial; the broadcaster’s editors and moderators may not start commercials on behalf of the broadcaster.

Authorization

Requires a user access token that includes the channel:edit:commercial scope.

URL

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

Request Body

Field	Type	Description
broadcaster_id	String	The ID of the partner or affiliate broadcaster that wants to run the commercial. This ID must match the user ID found in the OAuth token.
length	Integer	The length of the commercial to run, in seconds. Twitch tries to serve a commercial that’s the requested length, but it may be shorter or longer. The maximum length you should request is 180 seconds.

Response Body

Field	Type	Description
data	Object[]	An array that contains a single object with the status of your start commercial request.
length	Integer	The length of the commercial you requested. If you request a commercial that’s longer than 180 seconds, the API uses 180 seconds.
message	String	A message that indicates whether Twitch was able to serve an ad.
retry_after	Integer	The number of seconds you must wait before running another commercial.

Response Codes

Code	Description
200 OK	Successfully started the commercial.
400 Bad Request	The broadcaster_id query parameter is required. The length query parameter is required. The ID in broadcaster_id is not valid. To start a commercial, the broadcaster must be streaming live. The broadcaster may not run another commercial until the cooldown period expires. The `retry_after` field in the previous start commercial response specifies the amount of time the broadcaster must wait between running commercials.
401 Unauthorized	The ID in `broadcaster_id` must match the user ID found in the request’s OAuth token. The Authorization header is required and must contain a user access token. The user access token must include the channel:edit:commercial 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.
404 Not Found	The ID in `broadcaster_id` was not found.
429 Too Many Requests	The broadcaster may not run another commercial until the cooldown period expires. The `retry_after` field in the previous start commercial response specifies the amount of time the broadcaster must wait between running commercials.

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 Ad Schedule

✎

This endpoint returns ad schedule related information, including snooze, when the last ad was run, when the next ad is scheduled, and if the channel is currently in pre-roll free time. Note that a new ad cannot be run until 8 minutes after running a previous ad.

Authorization

Requires a user access token that includes the channel:read:ads scope. The user_id in the user access token must match the broadcaster_id.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	Provided `broadcaster_id` must match the `user_id` in the auth token.

Response Body

Field	Type	Description
data	Object[]	A list that contains information related to the channel’s ad schedule.
snooze_count	Integer	The number of snoozes available for the broadcaster.
snooze_refresh_at	String	The UTC timestamp when the broadcaster will gain an additional snooze, in RFC3339 format.
next_ad_at	String	The UTC timestamp of the broadcaster’s next scheduled ad, in RFC3339 format. Empty if the channel has no ad scheduled or is not live.
duration	Integer	The length in seconds of the scheduled upcoming ad break.
last_ad_at	String	The UTC timestamp of the broadcaster’s last ad-break, in RFC3339 format. Empty if the channel has not run an ad or is not live.
preroll_free_time	Integer	The amount of pre-roll free time remaining for the channel in seconds. Returns 0 if they are currently not pre-roll free.

Response Codes

Code	Description
200 OK	Returns the ad schedule information for the channel.
400 Bad Request	The broadcaster ID is not valid.
500 Internal Server Error

Example Request

Snooze the next ad.

curl -X GET 'https://api.twitch.tv/helix/channels/ads?broadcaster_id=123' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "next_ad_at" : "2023-08-01T23:08:18+00:00",
      "last_ad_at" : "2023-08-01T23:08:18+00:00",
      "duration" : "60",
      "preroll_free_time" : "90",
      "snooze_count" : "1",
      "snooze_refresh_at" : "2023-08-01T23:08:18+00:00",
    },
  ],
}

Snooze Next Ad

✎

If available, pushes back the timestamp of the upcoming automatic mid-roll ad by 5 minutes. This endpoint duplicates the snooze functionality in the creator dashboard’s Ads Manager.

Authorization

Requires a user access token that includes the channel:manage:ads scope. The user_id in the user access token must match the broadcaster_id.

URL

POST https://api.twitch.tv/helix/channels/ads/schedule/snooze

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	Provided `broadcaster_id` must match the `user_id` in the auth token.

Response Body

Field	Type	Description
data	Object[]	A list that contains information about the channel’s snoozes and next upcoming ad after successfully snoozing.
snooze_count	Integer	The number of snoozes available for the broadcaster.
snooze_refresh_at	String	The UTC timestamp when the broadcaster will gain an additional snooze, in RFC3339 format.
next_ad_at	String	The UTC timestamp of the broadcaster’s next scheduled ad, in RFC3339 format.

Response Codes

Code	Description
200 OK	User’s next ad is successfully snoozed. Their snooze_count is decremented and snooze_refresh_time and next_ad_at are both updated.
400 Bad Request	The channel is not currently live. The broadcaster ID is not valid. Channel does not have an upcoming scheduled ad break.
429 Too Many Requests	Channel has no snoozes left.
500 Internal Server Error

Example Request

Snooze the next ad.

curl -X POST 'https://api.twitch.tv/helix/channels/ads/schedule/snooze?broadcaster_id=123' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "snooze_count" : "1",
      "snooze_refresh_at" : "2023-08-01T23:08:18+00:00",
      "next_ad_at" : "2023-08-01T23:08:18+00:00",
    },
  ],
}

Get Extension Analytics

✎

Gets an analytics report for one or more extensions. The response contains the URLs used to download the reports (CSV files). Learn More

Authorization

Requires a user access token that includes the analytics:read:extensions scope.

URL

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

Request Query Parameters

Name	Type	Required?	Description
extension_id	String	No	The extension's client ID. If specified, the response contains a report for the specified extension. If not specified, the response includes a report for each extension that the authenticated user owns.
type	String	No	The type of analytics report to get. Possible values are: overview_v2
started_at	String	No	The reporting window's start date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-22T00:00:00Z). The start date must be on or after January 31, 2018. If you specify an earlier date, the API ignores it and uses January 31, 2018. If you specify a start date, you must specify an end date. If you don't specify a start and end date, the report includes all available data since January 31, 2018. The report contains one row of data for each day in the reporting window.
ended_at	String	No	The reporting window's end date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-27T00:00:00Z). The report is inclusive of the end date. Specify an end date only if you provide a start date. Because it can take up to two days for the data to be available, you must specify an end date that's earlier than today minus one to two days. If not, the API ignores your end date and uses an end date that is today minus one to two days.
first	Integer	No	The maximum number of report URLs to return per page in the response. The minimum page size is 1 URL per page and the maximum is 100 URLs per page. The default is 20. NOTE: While you may specify a maximum value of 100, the response will contain at most 20 URLs per page.
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 This parameter is ignored if the extension_id parameter is set.

Response Body

Field	Type	Description
data	Object[]	A list of reports. The reports are returned in no particular order; however, the data within each report is in ascending order by date (newest first). The report contains one row of data per day of the reporting window; the report contains rows for only those days that the extension was used. The array is empty if there are no reports.
extension_id	String	An ID that identifies the extension that the report was generated for.
URL	String	The URL that you use to download the report. The URL is valid for 5 minutes.
type	String	The type of report.
date_range	Object	The reporting window’s start and end dates, in RFC3339 format.
started_at	String	The reporting window’s start date.
ended_at	String	The reporting window’s end date.
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	Description
200 OK	Successfully retrieved the broadcaster's analytics reports.
400 Bad Request	The start and end dates are optional but if you specify one, you must specify the other. The end date must be equal to or later than the start date. The cursor specified in the after query parameter is not valid. The resource supports only forward pagination (use the after query parameter). The first query parameter is outside the allowed range of values.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include the analytics:read:extensions scope. The OAuth token is not valid. The Client-Id header is required. The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
404 Not Found	The extension specified in the extension_id query parameter was not found.

Example Request

Gets the URLs for all reports for all extensions of the authenticated client. The request was 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

{
   "data": [
      {
         "extension_id": "efgh",
         "URL": "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/dynamic/LoL%20ADC...",
         "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 an analytics report for one or more games. The response contains the URLs used to download the reports (CSV files). Learn more

Authorization

Requires a user access token that includes the analytics:read:games scope.

URL

GET https://api.twitch.tv/helix/analytics/games

Request Query Parameters

Name	Type	Required?	Description
game_id	String	No	The game’s client ID. If specified, the response contains a report for the specified game. If not specified, the response includes a report for each of the authenticated user’s games.
type	String	No	The type of analytics report to get. Possible values are: overview_v2
started_at	String	No	The reporting window’s start date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-22T00:00:00Z). If you specify a start date, you must specify an end date. The start date must be within one year of today’s date. If you specify an earlier date, the API ignores it and uses a date that’s one year prior to today’s date. If you don’t specify a start and end date, the report includes all available data for the last 365 days from today. The report contains one row of data for each day in the reporting window.
ended_at	String	No	The reporting window’s end date, in RFC3339 format. Set the time portion to zeroes (for example, 2021-10-22T00:00:00Z). The report is inclusive of the end date. Specify an end date only if you provide a start date. Because it can take up to two days for the data to be available, you must specify an end date that’s earlier than today minus one to two days. If not, the API ignores your end date and uses an end date that is today minus one to two days.
first	Integer	No	The maximum number of report URLs to return per page in the response. The minimum page size is 1 URL per page and the maximum is 100 URLs per page. The default is 20. NOTE: While you may specify a maximum value of 100, the response will contain at most 20 URLs per page.
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 This parameter is ignored if game_id parameter is set.

Response Body

Field	Type	Description
data	Object[]	A list of reports. The reports are returned in no particular order; however, the data within each report is in ascending order by date (newest first). The report contains one row of data per day of the reporting window; the report contains rows for only those days that the game was used. A report is available only if the game was broadcast for at least 5 hours over the reporting period. The array is empty if there are no reports.
game_id	String	An ID that identifies the game that the report was generated for.
URL	String	The URL that you use to download the report. The URL is valid for 5 minutes.
type	String	The type of report.
date_range	Object	The reporting window’s start and end dates, in RFC3339 format.
started_at	String	The reporting window’s start date.
ended_at	String	The reporting window’s end date.
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	Description
200 OK	Successfully retrieved the broadcaster’s analytics reports.
400 Bad Request	The start and end dates are optional but if you specify one, you must specify the other. The end date must be equal to or later than the start date. The cursor specified in the after query parameter is not valid. The resource supports only forward pagination (use the after query parameter). The first query parameter is outside the allowed range of values.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include the analytics:read:games scope. The OAuth token is not valid. The Client-Id header is required. The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
404 Not Found	The game specified in the game_id query parameter was not found.

Example Request

Gets the URL for a downloadable CSV report for game ID 493057, covering the period January 1, 2018 through 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

{
  "data": [
    {
      "game_id" : "493057",
      "URL" : "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/games/66170/overview/15183...",
      "type" : "overview_v2",
      "date_range" : {
        "started_at" : "2018-01-01T00:00:00Z",
        "ended_at" : "2018-03-01T00:00:00Z"
      }
    }
  ]
}

Example Request

Gets the first 5 URLs for all reports for all games of the authenticated client. The request was 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

{
  "data": [
    {
      "game_id": "9821",
      "URL": "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/games/9821/overview/152642...",
      "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 the Bits leaderboard for the authenticated broadcaster.

Authorization

Requires a user access token that includes the bits:read scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
count	Integer	No	The number of results to return. The minimum count is 1 and the maximum is 100. The default is 10.
period	String	No	The time period over which data is aggregated (uses the PST time zone). Possible values are: day — A day spans from 00:00:00 on the day specified in started_at and runs through 00:00:00 of the next day. week — A week spans from 00:00:00 on the Monday of the week specified in started_at and runs through 00:00:00 of the next Monday. month — A month spans from 00:00:00 on the first day of the month specified in started_at and runs through 00:00:00 of the first day of the next month. year — A year spans from 00:00:00 on the first day of the year specified in started_at and runs through 00:00:00 of the first day of the next year. all — Default. The lifetime of the broadcaster's channel.
started_at	String	No	The start date, in RFC3339 format, used for determining the aggregation period. Specify this parameter only if you specify the period query parameter. The start date is ignored if period is all. Note that the date is converted to PST before being used, so if you set the start time to `2022-01-01T00:00:00.0Z` and period to month, the actual reporting period is December 2021, not January 2022. If you want the reporting period to be January 2022, you must set the start time to `2022-01-01T08:00:00.0Z` or `2022-01-01T00:00:00.0-08:00`. If your start date uses the ‘+’ offset operator (for example, `2022-01-01T00:00:00.0+05:00`), you must URL encode the start date.
user_id	String	No	An ID that identifies a user that cheered bits in the channel. If count is greater than 1, the response may include users ranked above and below the specified user. To get the leaderboard’s top leaders, don’t specify a user ID.

Response Body

Field	Type	Description
data	Object[]	A list of leaderboard leaders. The leaders are returned in rank order by how much they’ve cheered. The array is empty if nobody has cheered bits.
user_id	String	An ID that identifies a user on the leaderboard.
user_login	String	The user’s login name.
user_name	String	The user’s display name.
rank	Integer	The user’s position on the leaderboard.
score	Integer	The number of Bits the user has cheered.
date_range	Object	The reporting window’s start and end dates, in RFC3339 format. The dates are calculated by using the started_at and period query parameters. If you don’t specify the started_at query parameter, the fields contain empty strings.
started_at	String	The reporting window’s start date.
ended_at	String	The reporting window’s end date.
total	Integer	The number of ranked users in `data`. This is the value in the count query parameter or the total number of entries on the leaderboard, whichever is less.

Response Codes

Code	Description
200 OK	Successfully retrieved the broadcaster’s Bits leaderboard.
400 Bad Request	The time period specified in the period query parameter is not valid. The started_at query parameter is required if period is not set to all. The value in the count query parameter is outside the range of allowed values.
401 Unauthorized	The Authorization header is required and must specify a user access token. The user access token must include the the bits:read scope. The access token is not valid. The ID in the Client-Id header must match the client ID in the access token.
403 Forbidden

Example Request

Gets information about the authenticated broadcaster’s top two Bits leaderboard entries for the specified week.

curl -X GET 'https://api.twitch.tv/helix/bits/leaderboard?count=2&period=week&started_at=2018-02-05T08%3A00%3A00Z' \
-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

✎

Gets a list of Cheermotes that users can use to cheer Bits in any Bits-enabled channel’s chat room. Cheermotes are animated emotes that viewers can assign Bits to.

URL

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

Authorization

Requires an app access token or user access token.

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	No	The ID of the broadcaster whose custom Cheermotes you want to get. Specify the broadcaster’s ID if you want to include the broadcaster’s Cheermotes in the response (not all broadcasters upload Cheermotes). If not specified, the response contains only global Cheermotes. If the broadcaster uploaded Cheermotes, the `type` field in the response is set to channel_custom.

Response Body

Field	Type	Description
data	Object[]	The list of Cheermotes. The list is in ascending order by the `order` field’s value.
prefix	String	The name portion of the Cheermote string that you use in chat to cheer Bits. The full Cheermote string is the concatenation of {prefix} + {number of Bits}. For example, if the prefix is “Cheer” and you want to cheer 100 Bits, the full Cheermote string is Cheer100. When the Cheermote string is entered in chat, Twitch converts it to the image associated with the Bits tier that was cheered.
tiers	Object[]	A list of tier levels that the Cheermote supports. Each tier identifies the range of Bits that you can cheer at that tier level and an image that graphically identifies the tier level.
min_bits	Integer	The minimum number of Bits that you must cheer at this tier level. The maximum number of Bits that you can cheer at this level is determined by the required minimum Bits of the next tier level minus 1. For example, if `min_bits` is 1 and `min_bits` for the next tier is 100, the Bits range for this tier level is 1 through 99. The minimum Bits value of the last tier is the maximum number of Bits you can cheer using this Cheermote. For example, 10000.
id	String	The tier level. Possible tiers are: 1 100 500 1000 5000 10000 100000
color	String	The hex code of the color associated with this tier level (for example, #979797).
images	Dictionary	The animated and static image sets for the Cheermote. The dictionary of images is organized by theme, format, and size. The theme keys are dark and light. Each theme is a dictionary of formats: animated and static. Each format is a dictionary of sizes: 1, 1.5, 2, 3, and 4. The value of each size contains the URL to the image.
can_cheer	Boolean	A Boolean value that determines whether users can cheer at this tier level.
show_in_bits_card	Boolean	A Boolean value that determines whether this tier level is shown in the Bits card. Is true if this tier level is shown in the Bits card.
type	String	The type of Cheermote. Possible values are: global_first_party — A Twitch-defined Cheermote that is shown in the Bits card. global_third_party — A Twitch-defined Cheermote that is not shown in the Bits card. channel_custom — A broadcaster-defined Cheermote. display_only — Do not use; for internal use only. sponsored — A sponsor-defined Cheermote. When used, the sponsor adds additional Bits to the amount that the user cheered. For example, if the user cheered Terminator100, the broadcaster might receive 110 Bits, which includes the sponsor's 10 Bits contribution.
order	Integer	The order that the Cheermotes are shown in the Bits card. The numbers may not be consecutive. For example, the numbers may jump from 1 to 7 to 13. The order numbers are unique within a Cheermote type (for example, global_first_party) but may not be unique amongst all Cheermotes in the response.
last_updated	String	The date and time, in RFC3339 format, when this Cheermote was last updated.
is_charitable	Boolean	A Boolean value that indicates whether this Cheermote provides a charitable contribution match during charity campaigns.

Response Codes

Code	Description
200 OK	Successfully retrieved the Cheermotes.
401 Unauthorized	The Authorization header is required and must specify an app access token or user access token. The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Requests

Gets a list of all global Cheermotes.

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

Gets a list of all global Cheermotes and any Cheermotes that the broadcaster has uploaded.

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 an extension’s list of transactions. A transaction records the exchange of a currency (for example, Bits) for a digital product.

Authorization

Requires an app access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
extension_id	String	Yes	The ID of the extension whose list of transactions you want to get.
id	String	No	A transaction ID used to filter the list of transactions. Specify this parameter for each transaction you want to get. For example, `id=1234&id=5678`. You may specify a maximum of 100 IDs.
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 items per page. 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 transactions.
id	String	An ID that identifies the transaction.
timestamp	String	The UTC date and time (in RFC3339 format) of the transaction.
broadcaster_id	String	The ID of the broadcaster that owns the channel where the transaction occurred.
broadcaster_login	String	The broadcaster’s login name.
broadcaster_name	String	The broadcaster’s display name.
user_id	String	The ID of the user that purchased the digital product.
user_login	String	The user’s login name.
user_name	String	The user’s display name.
product_type	String	The type of transaction. Possible values are: BITS_IN_EXTENSION
product_data	Object	Contains details about the digital product.
sku	String	An ID that identifies the digital product.
domain	String	Set to `twitch.ext.` + `<the extension's ID>`.
cost	Object	Contains details about the digital product’s cost.
amount	Integer	The amount exchanged for the digital product.
type	String	The type of currency exchanged. Possible values are: bits
inDevelopment	Boolean	A Boolean value that determines whether the product is in development. Is true if the digital product is in development and cannot be exchanged.
displayName	String	The name of the digital product.
expiration	String	This field is always empty since you may purchase only unexpired products.
broadcast	Boolean	A Boolean value that determines whether the data was broadcast to all instances of the extension. Is true if the data was broadcast to all instances.
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	Description
200 OK	Successfully retrieved the list of transactions.
400 Bad Request	The extension_id query parameter is required. The request specified too many id query parameters. The pagination cursor is not valid.
401 Unauthorized	The Authorization header is required and must specify an app access token. The access token is not valid. The ID in the extension_id query parameter must match the client ID in the access token. The ID in the Client-Id header must match the client ID in the access token.
404 Not Found	One or more of the transaction IDs specified using the id query parameter were not found.

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 information about one or more channels.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	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. The API ignores duplicate IDs and IDs that are not found.

Response Body

Field	Type	Description
data	Object[]	A list that contains information about the specified channels. The list is empty if the specified channels weren’t found.
broadcaster_id	String	An ID that uniquely identifies the broadcaster.
broadcaster_login	String	The broadcaster’s login name.
broadcaster_name	String	The broadcaster’s display name.
broadcaster_language	String	The broadcaster’s preferred language. The value is an ISO 639-1 two-letter language code (for example, en for English). The value is set to “other” if the language is not a Twitch supported language.
game_name	String	The name of the game that the broadcaster is playing or last played. The value is an empty string if the broadcaster has never played a game.
game_id	String	An ID that uniquely identifies the game that the broadcaster is playing or last played. The value is an empty string if the broadcaster has never played a game.
title	String	The title of the stream that the broadcaster is currently streaming or last streamed. The value is an empty string if the broadcaster has never streamed.
delay	Unsigned Integer	The value of the broadcaster’s stream delay setting, in seconds. This field’s value defaults to zero unless 1) the request specifies a user access token, 2) the ID in the broadcaster_id query parameter matches the user ID in the access token, and 3) the broadcaster has partner status and they set a non-zero stream delay value.
tags	String[]	The tags applied to the channel.
content_classification_labels	String[]	The CCLs applied to the channel.
is_branded_content	Boolean	Boolean flag indicating if the channel has branded content.

Response Codes

HTTP Code	Description
200 OK	Successfully retrieved the list of channels.
400 Bad Request	The broadcaster_id query parameter is required. The broadcaster ID is not valid. The number of broadcaster_id query parameters exceeds the maximum allowed.
401 Unauthorized	The Authorization header is required and must specify an app access token or user access token. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.
429 Too Many Requests	The application exceeded the number of calls it may make per minute. For details, see Rate Limits.
500 Internal Server Error

Example 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,
      "tags": ["DevsInTheKnow"],
      "content_classification_labels": ["Gambling", "DrugsIntoxication", "MatureGame"],
      "is_branded_content": false
    }
  ]
}

Modify Channel Information

✎

Updates a channel’s properties.

Authorization

Requires a user access token that includes the channel:manage:broadcast scope.

URL

PATCH https://api.twitch.tv/helix/channels

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose channel you want to update. This ID must match the user ID in the user access token.

Request Body

All fields are optional, but you must specify at least one field.

Field	Type	Required?	Description
game_id	String	No	The ID of the game that the user plays. The game is not updated if the ID isn’t a game ID that Twitch recognizes. To unset this field, use “0” or “” (an empty string).
broadcaster_language	String	No	The user’s preferred language. Set the value to an ISO 639-1 two-letter language code (for example, en for English). Set to “other” if the user’s preferred language is not a Twitch supported language. The language isn’t updated if the language code isn’t a Twitch supported language.
title	String	No	The title of the user’s stream. You may not set this field to an empty string.
delay	Integer	No	The number of seconds you want your broadcast buffered before streaming it live. The delay helps ensure fairness during competitive play. Only users with Partner status may set this field. The maximum delay is 900 seconds (15 minutes).
tags	String[]	No	A list of channel-defined tags to apply to the channel. To remove all tags from the channel, set tags to an empty array. Tags help identify the content that the channel streams. Learn More A channel may specify a maximum of 10 tags. Each tag is limited to a maximum of 25 characters and may not be an empty string or contain spaces or special characters. Tags are case insensitive. For readability, consider using camelCasing or PascalCasing.
content_classification_labels	Label[]	No	List of labels that should be set as the Channel’s CCLs.
id	string	Yes	ID of the Content Classification Labels that must be added/removed from the channel. Can be one of the following values: DebatedSocialIssuesAndPolitics DrugsIntoxication SexualThemes ViolentGraphic Gambling ProfanityVulgarity
is_enabled	boolean	Yes	Boolean flag indicating whether the label should be enabled (true) or disabled for the channel.
is_branded_content	Boolean	No	Boolean flag indicating if the channel has branded content.

Response Codes

HTTP Code	Description
204 No Content	Successfully updated the channel’s properties.
400 Bad Request	The broadcaster_id query parameter is required. The request must update at least one property. The `title` field may not contain an empty string. The ID in `game_id` is not valid. To update the `delay` field, the broadcaster must have partner status. The list in the `tags` field exceeds the maximum number of tags allowed. A tag in the `tags` field exceeds the maximum length allowed. A tag in the `tags` field is empty. A tag in the `tags` field contains special characters or spaces. One or more tags in the `tags` field failed AutoMod review. Game restricted for user's age and region
401 Unauthorized	User requests CCL for a channel they don’t own The ID in broadcaster_id must match the user ID found in the OAuth token. The Authorization header is required and must specify a user access token. The OAuth token must include the channel:manage:broadcast scope. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden	User requested gaming CCLs to be added to their channel Unallowed CCLs declared for underaged authorized user in a restricted country
409 Too Many Requests	User set the Branded Content flag too frequently
500 Internal server error

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", "tags":["LevelingUp"]}'

Set CCLs for a Channel

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”: “SomeGameID”,
    “content_classification_labels”: [
       {“id”: “Gambling”, “is_enabled”: true}, // adds this label
       {“id”: “DrugsIntoxication”, “is_enabled”: false}  // removes this label
     ],
    “is_branded_content”: true
}'

Get Channel Editors

✎

Gets the broadcaster’s list editors.

Authorization

Requires a user access token that includes the channel:read:editors scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that owns the channel. This ID must match the user ID in the access token.

Response Body

Field	Type	Description
data	Object[]	A list of users that are editors for the specified broadcaster. The list is empty if the broadcaster doesn’t have editors.
user_id	String	An ID that uniquely identifies a user with editor permissions.
user_name	String	The user’s display name.
created_at	String	The date and time, in RFC3339 format, when the user became one of the broadcaster’s editors.

Response Codes

Code	Description
200 OK	Successfully retrieved the broadcaster's list of editors.
400 Bad Request	The broadcaster_id query parameter is required.
401 Unauthorized	The ID in the broadcaster_id query parameter must match the user ID found in the OAuth token. The Authorization header is required and must specify a user access token. The OAuth token must include the channel:read:editors scope. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

Gets the list of editors for TwitchDev.

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

Get Followed Channels

✎

Gets a list of broadcasters that the specified user follows. You can also use this endpoint to see whether a user follows a specific broadcaster.

Authorization

Requires a user access token that includes the user:read:follows scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
user_id	String	Yes	A user’s ID. Returns the list of broadcasters that this user follows. This ID must match the user ID in the user OAuth token.
broadcaster_id	String	No	A broadcaster’s ID. Use this parameter to see whether the user follows this broadcaster. If specified, the response contains this broadcaster if the user follows them. If not specified, the response contains all broadcasters that the user follows.
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 broadcasters that the user follows. The list is in descending order by `followed_at` (with the most recently followed broadcaster first). The list is empty if the user doesn’t follow anyone.
broadcaster_id	String	An ID that uniquely identifies the broadcaster that this user is following.
broadcaster_login	String	The broadcaster’s login name.
broadcaster_name	String	The broadcaster’s display name.
followed_at	String	The UTC timestamp when the user started following the broadcaster.
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.
total	Integer	The total number of broadcasters that the user follows. As someone pages through the list, the number may change as the user follows or unfollows broadcasters.

Response Codes

Code	Description
200 OK	Successfully retrieved the broadcaster's list of followers.
400 Bad Request	Possible reasons: The user_id query parameter is required. The broadcaster_id query parameter is not valid. The user_id query parameter is required.
401 Unauthorized	Possible reasons: The ID in the user_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 is missing the user:read:follows 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.

Example Request

Gets the list of broadcasters that the specified user follows.

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

Example Response

{
  "total": 8
  "data": [
    {
      "broadcaster_id": "11111",
      "broadcaster_login": "userloginname",
      "broadcaster_name": "UserDisplayName",
      "followed_at": "2022-05-24T22:22:08Z",
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"
  }
}

Example Request

Checks whether the specified user follows the specified broadcaster.

curl -X GET 'https://api.twitch.tv/helix/channels/followed?user_id=123456&broadcaster_id=654321' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'

Example Response

The data field is not an empty array, which means that the user does follow the specified broadcaster.

{
  "total": 8
  "data": [
    {
      "broadcaster_id": "654321",
      "broadcaster_login": "basketweaver101",
      "broadcaster_name": "BasketWeaver101",
      "followed_at": "2022-05-24T22:22:08Z",
    }
  ],
  "pagination": {}
}

Get Channel Followers

✎

Gets a list of users that follow the specified broadcaster. You can also use this endpoint to see whether a specific user follows the broadcaster.

Authorization

Requires a user access token that includes the moderator:read:followers scope.
The ID in the broadcaster_id query parameter must match the user ID in the access token or the user ID in the access token must be a moderator for the specified broadcaster.

This endpoint will return specific follower information only if both of the above are true. If a scope is not provided or the user isn’t the broadcaster or a moderator for the specified channel, only the total follower count will be included in the response.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
user_id	String	No	A user’s ID. Use this parameter to see whether the user follows this broadcaster. If specified, the response contains this user if they follow the broadcaster. If not specified, the response contains all users that follow the broadcaster. Using this parameter requires both a user access token with the moderator:read:followers scope and the user ID in the access token match the broadcaster_id or be the user ID for a moderator of the specified broadcaster.
broadcaster_id	String	Yes	The broadcaster’s ID. Returns the list of users that follow this broadcaster.
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 users that follow the specified broadcaster. The list is in descending order by `followed_at` (with the most recent follower first). The list is empty if nobody follows the broadcaster, the specified `user_id` isn’t in the follower list, the user access token is missing the moderator:read:followers scope, or the user isn’t the broadcaster or moderator for the channel.
followed_at	String	The UTC timestamp when the user started following the broadcaster.
user_id	String	An ID that uniquely identifies the user that’s following the broadcaster.
user_login	String	The user’s login name.
user_name	String	The user’s display 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.
total	Integer	The total number of users that follow this broadcaster. As someone pages through the list, the number of users may change as users follow or unfollow the broadcaster.

Response Codes

Code	Description
200 OK	Successfully retrieved the broadcaster’s list of followers.
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 or the user must be a moderator for the specified broadcaster. The Authorization header is required and must contain a user access token. The user access token is missing the moderator:read:followers 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. The user_id parameter was specified but either the user access token is missing the moderator:read:followers scope or the user is not the broadcaster or moderator for the specified channel

Example Request

Gets the list of users that follow the specified broadcaster.

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

Example Response

{
  "total": 8
  "data": [
    {
      "user_id": "11111",
      "user_name": "UserDisplayName",
      "user_login": "userloginname",
      "followed_at": "2022-05-24T22:22:08Z",
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"
  }
}

Example Request

Checks whether the specified user follows the specified broadcaster.

curl -X GET 'https://api.twitch.tv/helix/channels/followers?broadcaster_id=123456&user_id=654321' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'

Example Response

The data field is an empty array, which means the user doesn’t follow the specified broadcaster.

{
  "total": 8
  "data": [],
  "pagination": {}
}

Create Custom Rewards

✎

Creates a Custom Reward in the broadcaster’s channel. The maximum number of custom rewards per channel is 50, which includes both enabled and disabled rewards.

Authorization

Requires a user access token that includes the channel:manage:redemptions scope.

URL

POST https://api.twitch.tv/helix/channel_points/custom_rewards

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster to add the custom reward to. This ID must match the user ID found in the OAuth token.

Request Body

Field	Type	Required?	Description
title	String	Yes	The custom reward’s title. The title may contain a maximum of 45 characters and it must be unique amongst all of the broadcaster’s custom rewards.
cost	Int64	Yes	The cost of the reward, in Channel Points. The minimum is 1 point.
prompt	String	No	The prompt shown to the viewer when they redeem the reward. Specify a prompt if `is_user_input_required` is true. The prompt is limited to a maximum of 200 characters.
is_enabled	Boolean	No	A Boolean value that determines whether the reward is enabled. Viewers see only enabled rewards. The default is true.
background_color	String	No	The background color to use for the reward. Specify the color using Hex format (for example, #9147FF).
is_user_input_required	Boolean	No	A Boolean value that determines whether the user needs to enter information when redeeming the reward. See the `prompt` field. The default is false.
is_max_per_stream_enabled	Boolean	No	A Boolean value that determines whether to limit the maximum number of redemptions allowed per live stream (see the `max_per_stream` field). The default is false.
max_per_stream	Integer	No	The maximum number of redemptions allowed per live stream. Applied only if `is_max_per_stream_enabled` is true. The minimum value is 1.
is_max_per_user_per_stream_enabled	Boolean	No	A Boolean value that determines whether to limit the maximum number of redemptions allowed per user per stream (see the `max_per_user_per_stream` field). The default is false.
max_per_user_per_stream	Integer	No	The maximum number of redemptions allowed per user per stream. Applied only if `is_max_per_user_per_stream_enabled` is true. The minimum value is 1.
is_global_cooldown_enabled	Boolean	No	A Boolean value that determines whether to apply a cooldown period between redemptions (see the `global_cooldown_seconds` field for the duration of the cooldown period). The default is false.
global_cooldown_seconds	Integer	No	The cooldown period, in seconds. Applied only if the `is_global_cooldown_enabled` field is true. The minimum value is 1; however, the minimum value is 60 for it to be shown in the Twitch UX.
should_redemptions_skip_request_queue	Boolean	No	A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process. The default is false.

Response Body

Field	Type	Description
data	Object[]	A list that contains the single custom reward you created.
broadcaster_id	String	The ID that uniquely identifies the broadcaster.
broadcaster_login	String	The broadcaster’s login name.
broadcaster_name	String	The broadcaster’s display name.
id	String	The ID that uniquely identifies this custom reward.
title	String	The title of the reward.
prompt	String	The prompt shown to the viewer when they redeem the reward if user input is required (see the `is_user_input_required` field).
cost	Integer	The cost of the reward in Channel Points.
image	Object	A set of custom images for the reward. This field is set to null if the broadcaster didn’t upload images.
url_1x	String	The URL to a small version of the image.
url_2x	String	The URL to a medium version of the image.
url_4x	String	The URL to a large version of the image.
default_image	Object	A set of default images for the reward.
url_1x	String	The URL to a small version of the image.
url_2x	String	The URL to a medium version of the image.
url_4x	String	The URL to a large version of the image.
background_color	String	The background color to use for the reward. The color is in Hex format (for example, #00E5CB).
is_enabled	Boolean	A Boolean value that determines whether the reward is enabled. Is true if enabled; otherwise, false. Disabled rewards aren’t shown to the user.
is_user_input_required	Boolean	A Boolean value that determines whether the user must enter information when redeeming the reward. Is true if the reward requires user input.
max_per_stream_setting	Object	The settings used to determine whether to apply a maximum to the number to the redemptions allowed per live stream.
is_enabled	Boolean	A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per live stream. Is true if the reward applies a limit.
max_per_stream	Int64	The maximum number of redemptions allowed per live stream.
max_per_user_per_stream_setting	Object	The settings used to determine whether to apply a maximum to the number of redemptions allowed per user per live stream.
is_enabled	Boolean	A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per user per live stream. Is true if the reward applies a limit.
max_per_user_per_stream	Int64	The maximum number of redemptions allowed per user per live stream.
global_cooldown_setting	Object	The settings used to determine whether to apply a cooldown period between redemptions and the length of the cooldown.
is_enabled	Boolean	A Boolean value that determines whether to apply a cooldown period. Is true if a cooldown period is enabled.
global_cooldown_seconds	Int64	The cooldown period, in seconds.
is_paused	Boolean	A Boolean value that determines whether the reward is currently paused. Is true if the reward is paused. Viewers can’t redeem paused rewards.
is_in_stock	Boolean	A Boolean value that determines whether the reward is currently in stock. Is true if the reward is in stock. Viewers can’t redeem out of stock rewards.
should_redemptions_skip_request_queue	Boolean	A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is UNFULFILLED and follows the normal request queue process.
redemptions_redeemed_current_stream	Integer	The number of redemptions redeemed during the current live stream. The number counts against the `max_per_stream_setting` limit. This field is null if the broadcaster’s stream isn’t live or max_per_stream_setting isn’t enabled.
cooldown_expires_at	String	The timestamp of when the cooldown period expires. Is null if the reward isn’t in a cooldown state (see the `global_cooldown_setting` field).

Response Codes

HTTP Code	Description
200 OK	Successfully created the custom reward.
400 Bad Request	The request exceeds the maximum number of rewards allowed per channel. The broadcaster_id query parameter is required. The `title` field is required. The `title` must contain a minimum of 1 character and a maximum of 45 characters. The `title` must be unique amongst all of the broadcaster's custom rewards. The `cost` field is required. The `cost` field must contain a minimum of 1 point. The `prompt` field is limited to a maximum of 200 characters. If `is_max_per_stream_enabled` is true, the minimum value for `max_per_stream` is 1. If `is_max_per_user_per_stream_enabled` is true, the minimum value for `max_per_user_per_stream` is 1. If `is_global_cooldown_enabled` is true, the minimum value for `global_cooldown_seconds` is 1.
401 Unauthorized	The Authorization header is required and must specify a user access token. The user access token is missing the channel:manage:redemptions scope. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden	The broadcaster is not a partner or affiliate.
500 Internal Server Error

Example 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 that the broadcaster created.

The app used to create the reward is the only app that may delete it. If the reward’s redemption status is UNFULFILLED at the time the reward is deleted, its redemption status is marked as FULFILLED.

Authorization

Requires a user access token that includes the channel:manage:redemptions scope.

URL

DELETE https://api.twitch.tv/helix/channel_points/custom_rewards

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that created the custom reward. This ID must match the user ID found in the OAuth token.
id	String	Yes	The ID of the custom reward to delete.

Response Codes

HTTP Code	Description
204 No Content	Successfully deleted the custom reward.
400 Bad Request	The broadcaster_id query parameter is required. The id query parameter is required.
401 Unauthorized	The Authorization header is required and must specify a user access token. The user access token must include the channel:manage:redemptions scope. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden	The ID in the Client-Id header must match the client ID used to create the custom reward. The broadcaster is not a partner or affiliate.
404 Not Found	The custom reward specified in the id query parameter was not found.
500 Internal Server Error

Example Request

Deletes the specified 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'

Get Custom Reward

✎

Gets a list of custom rewards that the specified broadcaster created.

NOTE: A channel may offer a maximum of 50 rewards, which includes both enabled and disabled rewards.

Authorization

Requires a user access token that includes the channel:read:redemptions or channel:manage:redemptions scope.

URL

GET https://api.twitch.tv/helix/channel_points/custom_rewards

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose custom rewards you want to get. This ID must match the user ID found in the OAuth token.
id	String	No	A list of IDs to filter the rewards by. To specify more than one ID, include this parameter for each reward you want to get. For example, `id=1234&id=5678`. You may specify a maximum of 50 IDs. Duplicate IDs are ignored. The response contains only the IDs that were found. If none of the IDs were found, the response is 404 Not Found.
only_manageable_rewards	Boolean	No	A Boolean value that determines whether the response contains only the custom rewards that the app may manage (the app is identified by the ID in the Client-Id header). Set to true to get only the custom rewards that the app may manage. The default is false.

Response Body

Field	Type	Description
data	Object[]	A list of custom rewards. The list is in ascending order by `id`. If the broadcaster hasn’t created custom rewards, the list is empty.
broadcaster_id	String	The ID that uniquely identifies the broadcaster.
broadcaster_login	String	The broadcaster’s login name.
broadcaster_name	String	The broadcaster’s display name.
id	String	The ID that uniquely identifies this custom reward.
title	String	The title of the reward.
prompt	String	The prompt shown to the viewer when they redeem the reward if user input is required (see the `is_user_input_required` field).
cost	Integer	The cost of the reward in Channel Points.
image	Object	A set of custom images for the reward. This field is null if the broadcaster didn’t upload images.
url_1x	String	The URL to a small version of the image.
url_2x	String	The URL to a medium version of the image.
url_4x	String	The URL to a large version of the image.
default_image	Object	A set of default images for the reward.
url_1x	String	The URL to a small version of the image.
url_2x	String	The URL to a medium version of the image.
url_4x	String	The URL to a large version of the image.
background_color	String	The background color to use for the reward. The color is in Hex format (for example, #00E5CB).
is_enabled	Boolean	A Boolean value that determines whether the reward is enabled. Is true if enabled; otherwise, false. Disabled rewards aren’t shown to the user.
is_user_input_required	Boolean	A Boolean value that determines whether the user must enter information when redeeming the reward. Is true if the user is prompted.
max_per_stream_setting	Object	The settings used to determine whether to apply a maximum to the number of redemptions allowed per live stream.
is_enabled	Boolean	A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per live stream. Is true if the reward applies a limit.
max_per_stream	Int64	The maximum number of redemptions allowed per live stream.
max_per_user_per_stream_setting	Object	The settings used to determine whether to apply a maximum to the number of redemptions allowed per user per live stream.
is_enabled	Boolean	A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per user per live stream. Is true if the reward applies a limit.
max_per_user_per_stream	Int64	The maximum number of redemptions allowed per user per live stream.
global_cooldown_setting	Object	The settings used to determine whether to apply a cooldown period between redemptions and the length of the cooldown.
is_enabled	Boolean	A Boolean value that determines whether to apply a cooldown period. Is true if a cooldown period is enabled.
global_cooldown_seconds	Int64	The cooldown period, in seconds.
is_paused	Boolean	A Boolean value that determines whether the reward is currently paused. Is true if the reward is paused. Viewers can’t redeem paused rewards.
is_in_stock	Boolean	A Boolean value that determines whether the reward is currently in stock. Is true if the reward is in stock. Viewers can’t redeem out of stock rewards.
should_redemptions_skip_request_queue	Boolean	A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process.
redemptions_redeemed_current_stream	Integer	The number of redemptions redeemed during the current live stream. The number counts against the `max_per_stream_setting` limit. This field is null if the broadcaster’s stream isn’t live or max_per_stream_setting isn’t enabled.
cooldown_expires_at	String	The timestamp of when the cooldown period expires. Is null if the reward isn’t in a cooldown state. See the `global_cooldown_setting` field.

Response Codes

HTTP Code	Meaning
200 OK	Successfully retrieved the broadcaster’s list of custom rewards.
400 Bad Request	The broadcaster_id query parameter is required. The request exceeds the maximum number of id query parameters that you may specify.
401 Unauthorized	The Authorization header must specify a user access token. The user access token must include the channel:read:redemptions scope. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden	The broadcaster is not a partner or affiliate.
404 Not Found	All of the custom rewards specified using the id query parameter were not found.
500 Internal Server Error

Example Request

Gets the broadcaster’s list of 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

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

Gets the list of 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

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

Gets the specified custom reward.

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

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

✎

Gets a list of redemptions for the specified custom reward. The app used to create the reward is the only app that may get the redemptions.

Authorization

Requires a user access token that includes the channel:read:redemptions or channel:manage:redemptions scope.

URL

GET https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that owns the custom reward. This ID must match the user ID found in the user OAuth token.
reward_id	String	Yes	The ID that identifies the custom reward whose redemptions you want to get.
status	String	Yes	The status of the redemptions to return. The possible case-sensitive values are: CANCELED FULFILLED UNFULFILLED NOTE: This field is required only if you don’t specify the id query parameter. NOTE: Canceled and fulfilled redemptions are returned for only a few days after they’re canceled or fulfilled.
id	String	No	A list of IDs to filter the redemptions by. To specify more than one ID, include this parameter for each redemption you want to get. For example, `id=1234&id=5678`. You may specify a maximum of 50 IDs. Duplicate IDs are ignored. The response contains only the IDs that were found. If none of the IDs were found, the response is 404 Not Found.
sort	String	No	The order to sort redemptions by. The possible case-sensitive values are: OLDEST NEWEST The default is OLDEST.
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
first	Integer	No	The maximum number of redemptions to return per page in the response. The minimum page size is 1 redemption per page and the maximum is 50. The default is 20.

Response Body

Field	Type	Description
data	Object[]	The list of redemptions for the specified reward. The list is empty if there are no redemptions that match the redemption criteria.
broadcaster_id	String	The ID that uniquely identifies the broadcaster.
broadcaster_login	String	The broadcaster’s login name.
broadcaster_name	string	The broadcaster’s display name.
id	String	The ID that uniquely identifies this redemption.
user_login	String	The user’s login name.
user_id	String	The ID that uniquely identifies the user that redeemed the reward.
user_name	String	The user’s display name.
user_input	String	The text the user entered at the prompt when they redeemed the reward; otherwise, an empty string if user input was not required.
status	String	The state of the redemption. Possible values are: CANCELED FULFILLED UNFULFILLED
redeemed_at	String	The date and time of when the reward was redeemed, in RFC3339 format.
reward	Object	The reward that the user redeemed.
id	String	The ID that uniquely identifies the redeemed reward.
title	String	The reward’s title.
prompt	String	The prompt displayed to the viewer if user input is required.
cost	Int64	The reward’s cost, in Channel Points.

Response Codes

HTTP Code	Description
200 Ok	Successfully retrieved the list of redeemed custom rewards.
400 Bad Request	The broadcaster_id query parameter is required. The reward_id query parameter is required. The status query parameter is required if you didn't specify the id query parameter. The value in the status query parameter is not valid. The value in the sort query parameter is not valid.
401 Unauthorized	The Authorization header is required and must specify a user access token. The user access token must include the channel:read:redemptions scope. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden	The ID in the Client-Id header must match the client ID used to create the custom reward. The broadcaster is not a partner or affiliate.
404 Not Found	All of the redemptions specified using the id query parameter were not found.
500 Internal Server Error

Example Request

Gets the list of redemptions that were canceled for the specified 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

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

Gets 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

{
  "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. The app used to create the reward is the only app that may update the reward.

Authorization

Requires a user access token that includes the channel:manage:redemptions scope.

URL

PATCH https://api.twitch.tv/helix/channel_points/custom_rewards

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that’s updating the reward. This ID must match the user ID found in the OAuth token.
id	String	Yes	The ID of the reward to update.

Request Body

The body of the request should contain only the fields you’re updating.

Field	Type	Required?	Description
title	String	No	The reward’s title. The title may contain a maximum of 45 characters and it must be unique amongst all of the broadcaster’s custom rewards.
prompt	String	No	The prompt shown to the viewer when they redeem the reward. Specify a prompt if `is_user_input_required` is true. The prompt is limited to a maximum of 200 characters.
cost	Int64	No	The cost of the reward, in channel points. The minimum is 1 point.
background_color	String	No	The background color to use for the reward. Specify the color using Hex format (for example, \#00E5CB).
is_enabled	Boolean	No	A Boolean value that indicates whether the reward is enabled. Set to true to enable the reward. Viewers see only enabled rewards.
is_user_input_required	Boolean	No	A Boolean value that determines whether users must enter information to redeem the reward. Set to true if user input is required. See the `prompt` field.
is_max_per_stream_enabled	Boolean	No	A Boolean value that determines whether to limit the maximum number of redemptions allowed per live stream (see the `max_per_stream` field). Set to true to limit redemptions.
max_per_stream	Int64	No	The maximum number of redemptions allowed per live stream. Applied only if `is_max_per_stream_enabled` is true. The minimum value is 1.
is_max_per_user_per_stream_enabled	Boolean	No	A Boolean value that determines whether to limit the maximum number of redemptions allowed per user per stream (see `max_per_user_per_stream`). The minimum value is 1. Set to true to limit redemptions.
max_per_user_per_stream	Int64	No	The maximum number of redemptions allowed per user per stream. Applied only if `is_max_per_user_per_stream_enabled` is true.
is_global_cooldown_enabled	Boolean	No	A Boolean value that determines whether to apply a cooldown period between redemptions. Set to true to apply a cooldown period. For the duration of the cooldown period, see `global_cooldown_seconds`.
global_cooldown_seconds	Int64	No	The cooldown period, in seconds. Applied only if `is_global_cooldown_enabled` is true. The minimum value is 1; however, for it to be shown in the Twitch UX, the minimum value is 60.
is_paused	Boolean	No	A Boolean value that determines whether to pause the reward. Set to true to pause the reward. Viewers can’t redeem paused rewards..
should_redemptions_skip_request_queue	Boolean	No	A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process.

Response Body

Parameter	Type	Description
data	Object[]	The list contains the single reward that you updated.
broadcaster_id	String	The ID that uniquely identifies the broadcaster.
broadcaster_login	String	The broadcaster’s login name.
broadcaster_name	String	The broadcaster’s display name.
id	String	The ID that uniquely identifies this custom reward.
title	String	The title of the reward.
prompt	String	The prompt shown to the viewer when they redeem the reward if user input is required. See the `is_user_input_required` field.
cost	Int64	The cost of the reward in Channel Points.
image	Object	A set of custom images for the reward. This field is null if the broadcaster didn’t upload images.
url_1x	String	The URL to a small version of the image.
url_2x	String	The URL to a medium version of the image.
url_4x	String	The URL to a large version of the image.
default_image	Object	A set of default images for the reward.
url_1x	String	The URL to a small version of the image.
url_2x	String	The URL to a medium version of the image.
url_4x	String	The URL to a large version of the image.
background_color	String	The background color to use for the reward. The color is in Hex format (for example, #00E5CB).
is_enabled	Boolean	A Boolean value that determines whether the reward is enabled. Is true if enabled; otherwise, false. Disabled rewards aren’t shown to the user.
is_user_input_required	Boolean	A Boolean value that determines whether the user must enter information when they redeem the reward. Is true if the user is prompted.
max_per_stream_setting	Object	The settings used to determine whether to apply a maximum to the number of redemptions allowed per live stream.
is_enabled	Boolean	A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per live stream. Is true if the reward applies a limit.
max_per_stream	Int64	The maximum number of redemptions allowed per live stream.
max_per_user_per_stream_setting	Object	The settings used to determine whether to apply a maximum to the number of redemptions allowed per user per live stream.
is_enabled	Boolean	A Boolean value that determines whether the reward applies a limit on the number of redemptions allowed per user per live stream. Is true if the reward applies a limit.
max_per_user_per_stream	Int64	The maximum number of redemptions allowed per user per live stream.
global_cooldown_setting	Object	The settings used to determine whether to apply a cooldown period between redemptions and the length of the cooldown.
is_enabled	Boolean	A Boolean value that determines whether to apply a cooldown period. Is true if a cooldown period is enabled.
global_cooldown_seconds	Int64	The cooldown period, in seconds.
is_paused	Boolean	A Boolean value that determines whether the reward is currently paused. Is true if the reward is paused. Viewers can’t redeem paused rewards.
is_in_stock	Boolean	A Boolean value that determines whether the reward is currently in stock. Is true if the reward is in stock. Viewers can’t redeem out of stock rewards.
should_redemptions_skip_request_queue	Boolean	A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If false, status is set to UNFULFILLED and follows the normal request queue process.
redemptions_redeemed_current_stream	Integer	The number of redemptions redeemed during the current live stream. The number counts against the `max_per_stream_setting` limit. This field is null if the broadcaster’s stream isn’t live or max_per_stream_setting isn’t enabled.
cooldown_expires_at	String	The timestamp of when the cooldown period expires. Is null if the reward isn’t in a cooldown state. See the `global_cooldown_setting` field.

Response Codes

HTTP Code	Description
200 OK	Successfully updated the custom reward.
400 Bad Request	ul> The broadcaster_id query parameter is required. The id query parameter is required. The `title` must contain a minimum of 1 character and a maximum of 45 characters. The `title` must be unique amongst all of the broadcaster's custom rewards. The `cost` field must contain a minimum of 1 point. The `prompt` field is limited to a maximum of 200 characters. If `is_max_per_stream_enabled` is true, the minimum value for `max_per_stream` is 1. If `is_max_per_user_per_stream_enabled` is true, the minimum value for `max_per_user_per_stream` is 1. If `is_global_cooldown_enabled` is true, the minimum value for `global_cooldown_seconds` is 1 and the maximum is 604800.
401 Unauthorized	The Authorization header is required and must specify a user access token. The user access token must include the channel:manage:redemptions scope. The OAuth token is not valide. The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden	The ID in the Client-Id header must match the client ID used to create the custom reward. The broadcaster is not a partner or affiliate.
404 Not Found	The custom reward specified in the id query parameter was not found.
500 Internal Server Error

Example Request

Disables the specified 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

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

Updates the reward’s title.

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

{
  "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 a redemption’s status. You may update a redemption only if its status is UNFULFILLED. The app used to create the reward is the only app that may update the redemption.

Authorization

Requires a user access token that includes the channel:manage:redemptions scope.

URL

PATCH https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions

Request Query Parameters

Parameter	Type	Required?	Description
id	String	Yes	A list of IDs that identify the redemptions to update. To specify more than one ID, include this parameter for each redemption you want to update. For example, `id=1234&id=5678`. You may specify a maximum of 50 IDs.
broadcaster_id	String	Yes	The ID of the broadcaster that’s updating the redemption. This ID must match the user ID in the user access token.
reward_id	String	Yes	The ID that identifies the reward that’s been redeemed.

Request Body

Field	Type	Required?	Description
status	String	Yes	The status to set the redemption to. Possible values are: CANCELED FULFILLED Setting the status to CANCELED refunds the user’s channel points.

Response Body

Field	Type	Description
data	Object[]	The list contains the single redemption that you updated.
broadcaster_id	String	The ID that uniquely identifies the broadcaster.
broadcaster_login	String	The broadcaster’s login name.
broadcaster_name	String	The broadcaster’s display name.
id	String	The ID that uniquely identifies this redemption..
user_id	String	The ID of the user that redeemed the reward.
user_name	String	The user’s display name.
user_login	String	The user’s login name.
reward	Object	An object that describes the reward that the user redeemed.
id	String	The ID that uniquely identifies the reward.
title	String	The reward’s title.
prompt	String	The prompt displayed to the viewer if user input is required.
cost	Int64	The reward’s cost, in Channel Points.
user_input	String	The text that the user entered at the prompt when they redeemed the reward; otherwise, an empty string if user input was not required.
status	String	The state of the redemption. Possible values are: CANCELED FULFILLED UNFULFILLED
redeemed_at	String	The date and time of when the reward was redeemed, in RFC3339 format.

Response Codes

HTTP Code	Description
200 OK	Successfully updated the redemption’s status.
400 Bad Request	The broadcaster_id query parameter is required. The reward_id query parameter is required. The id query parameter is required. The value in the status query parameter is not valid.
401 Unauthorized	The Authorization header is required and must specify a user access token. The user access token must include the channel:manage:redemptions scope. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden	The ID in the Client-Id header must match the client ID used to create the custom reward. The broadcaster is not a partner or affiliate.
404 Not Found	The custom reward specified in the reward_id query parameter was not found. The redemptions specified using the id query parameter were not found or their statuses weren't marked as UNFULFILLED.
500 Internal Server Error

Example Request

Updates a redemption’s 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

✎

Gets information about the charity campaign that a broadcaster is running. For example, the campaign’s fundraising goal and the current amount of donations.

To receive events when progress is made towards the campaign’s goal or the broadcaster changes the fundraising goal, subscribe to the channel.charity_campaign.progress subscription type.

Authorization

Requires a user access token that includes the channel:read:charity scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that’s currently running a charity campaign. This ID must match the user ID in the access token.

Response Body

Field	Type	Description
data	Object[]	A list that contains the charity campaign that the broadcaster is currently running. The list is empty if the broadcaster is not running a charity campaign; the campaign information is not available after the campaign ends.
id	String	An ID that identifies the charity campaign.
broadcaster_id	String	An ID that 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	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	The campaign’s fundraising goal. This field is null if the broadcaster has not defined a fundraising 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	The broadcaster_id query parameter is required. The broadcaster_id query parameter is not valid.
401 Unauthorized	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 access token is not valid. The client ID specified in the Client-Id header must match the client ID specified in the access token.
403 Forbidden	The broadcaster is not 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://abc.cloudfront.net/ppgf/1000/100.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 Charity Campaign Donations

✎

Gets the list of donations that users have made to the broadcaster’s active charity campaign.

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

Authorization

Requires a user access token that includes the channel:read:charity scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that’s currently running a charity campaign. This ID must match the user ID in the access token.
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[]	A list that contains the donations that users have made to the broadcaster’s charity campaign. The list is empty if the broadcaster is not currently running a charity campaign; the donation information is not available after the campaign ends.
id	String	An ID that identifies the donation. The ID is unique across campaigns.
campaign_id	String	An ID that identifies the charity campaign that the donation applies to.
user_id	String	An ID that identifies a user that donated money to the campaign.
user_login	String	The user’s login name.
user_name	String	The user’s display name.
amount	Object	An object that contains the amount of money that the user donated.
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`.
pagination	Object	An object that 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	Description
200 OK	Successfully retrieved the list of donations that users contributed to the broadcaster’s charity campaign.
400 Bad Request	The broadcaster_id query parameter is required. The broadcaster_id query parameter is not valid.
401 Unauthorized	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 access token is not valid. The client ID specified in the Client-Id header must match the client ID specified in the access token.
403 Forbidden	The broadcaster is not a partner or affiliate.

Example Request

Gets the broadcaster’s active charity campaign.

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

Example Response

{
  "data": [
    {
      "id": "a1b2c3-aabb-4455-d1e2f3",
      "campaign_id": "123-abc-456-def",
      "user_id": "5678",
      "user_login": "cool_user",
      "user_name": "Cool_User",
      "amount": {
        "value": 500,
        "decimal_places": 2,
        "currency": "USD"
      }
    },
    {
      "id": "z1y2x3-ccdd-6677-d1e2f3",
      "campaign_id": "123-abc-456-def",
      "user_id": "8765",
      "user_login": "cool_user2",
      "user_name": "Cool_User2",
      "amount": {
        "value": 10000,
        "decimal_places": 2,
        "currency": "USD"
      }
    },
    . . .
  ],
  "pagination" : {
      "cursor" : "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"
  }
}

Get Chatters

✎

Gets the list of users that are connected to the broadcaster’s chat session.

NOTE: There is a delay between when users join and leave a chat and when the list is updated accordingly.

To determine whether a user is a moderator or VIP, use the Get Moderators and Get VIPs endpoints. You can check the roles of up to 100 users.

Authorization

Requires a user access token that includes the moderator:read:chatters scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose list of chatters you want to get.
moderator_id	String	Yes	The ID of the broadcaster or one of the broadcaster’s moderators. This ID must match the user ID in the user access token.
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 1,000. The default is 100.
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 users that are connected to the broadcaster’s chat room. The list is empty if no users are connected to the chat room.
user_id	String	The ID of a user that’s connected to the broadcaster’s chat room.
user_login	String	The user’s login name.
user_name	String	The user’s display 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.
total	Integer	The total number of users that are connected to the broadcaster’s chat room. As you page through the list, the number of users may change as users join and leave the chat room.

Response Codes

Code	Description
200 OK	Successfully retrieved the broadcaster’s list of chatters.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the broadcaster_id query parameter is not valid. The moderator_id query parameter is required. The ID in the moderator_id query parameter is not valid.
401 Unauthorized	The ID in the moderator_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 moderator:read:chatters scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in the moderator_id query parameter is not one of the broadcaster's moderators.

Example Request

Gets the list of users that are connected to the specified broadcaster’s chat room.

curl -X GET 'https://api.twitch.tv/helix/chat/chatters?broadcaster_id=123456&moderator_id=654321' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'

Example Response

{
  "data": [
    {
      "user_id": "128393656",
      "user_login": "smittysmithers",
      "user_name": "smittysmithers"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"
  },
  "total": 8
}

Get Channel Emotes

✎

Gets the broadcaster’s list of custom emotes. Broadcasters create these custom emotes for users who subscribe to or follow the channel or cheer Bits in the channel’s chat window. Learn More

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.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	An ID that identifies the broadcaster whose emotes you want to get.

Response Body

Field	Type	Description
data	Object[]	The list of emotes that the specified broadcaster created. If the broadcaster hasn't created custom emotes, the list is empty.
id	String	An ID that identifies this 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	The image URLs for the emote. These image URLs always provide a static, non-animated emote image with a light background. NOTE: You should 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 — A custom Bits tier emote. follower — A custom follower emote. subscriptions — A custom subscriber emote.
emote_set_id	String	An ID that identifies the emote set that the emote belongs to.
format	String[]	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 the emote is available as a static PNG and an animated GIF, the array contains `static` and `animated`. The possible formats are: animated — An animated GIF is available for this emote. static — A static PNG file is available for this emote.
scale	String[]	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[]	The background themes that the emote is available in. Possible themes are: dark light
template	String	A templated URL. Use the values from the `id`, `format`, `scale`, and `theme_mode` fields 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. You should use this template instead of using the URLs in the `images` object.

Response Codes

Code	Description
200 OK	Successfully retrieved broadcaster's list of custom emotes.
400 Bad Request	The broadcaster_id query parameter is required.
401 Unauthorized	The Authorization header is required and must specify a valid app access token or user access token. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

Gets custom emotes that the TwitchDev channel created.

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 the list of global emotes. Global emotes are Twitch-created emotes that users can use in any Twitch chat.

Learn More

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

None

Response Body

Field	Type	Description
data	Object[]	The list of global emotes.
id	String	An ID that identifies this 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	The image URLs for the emote. These image URLs always provide a static, non-animated emote image with a light background. NOTE: You should 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[]	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 the emote is available as a static PNG and an animated GIF, the array contains `static` and `animated`. The possible formats are: animated — An animated GIF is available for this emote. static — A static PNG file is available for this emote.
scale	String[]	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[]	The background themes that the emote is available in. Possible themes are: dark light
template	String	A templated URL. Use the values from the `id`, `format`, `scale`, and `theme_mode` fields 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. You should use this template instead of using the URLs in the `images` object.

Response Codes

Code	Description
200 OK	Successfully retrieved Twitch's list of global emotes.
401 Unauthorized	The Authorization header is required and must specify a valid app access token or user access token. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

Gets 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 gets 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 an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
emote_set_id	String	Yes	An ID that identifies the emote set to get. Include this 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. The response contains only the IDs that were found and ignores duplicate IDs. To get emote set IDs, use the Get Channel Emotes API.

Response Body

Field	Type	Description
data	Object[]	The list of emotes found in the specified emote sets. The list is empty if none of the IDs were found. The list is in the same order as the set IDs specified in the request. Each set contains one or more emoticons.
id	String	An ID that uniquely identifies this 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	The image URLs for the emote. These image URLs always provide a static, non-animated emote image with a light background. NOTE: You should 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 — A Bits tier emote. follower — A follower emote. subscriptions — 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[]	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 the emote is available as a static PNG and an animated GIF, the array contains `static` and `animated`. The possible formats are: animated — An animated GIF is available for this emote. static — A static PNG file is available for this emote.
scale	String[]	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[]	The background themes that the emote is available in. Possible themes are: dark light
template	string	A templated URL. Use the values from the `id`, `format`, `scale`, and `theme_mode` fields 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. You should use this template instead of using the URLs in the `images` object.

Response Codes

Code	Description
200 OK	Successfully retrieved the emotes for the specified emote sets.
400 Bad Request	The emote_set_id query parameter is required. The number of emote_set_id query parameters exceeds the maximum allowed.
401 Unauthorized	The Authorization header is required and must specify a valid app access token or user access token. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

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'

# Twitch 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 the broadcaster’s list of custom chat badges. The list is empty if the broadcaster hasn’t created custom chat badges. For information about custom badges, see subscriber badges and Bits badges.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameter

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose chat badges you want to get.

Response Body

Field	Type	Description
data	Object[]	The list of chat badges. The list is sorted in ascending order by `set_id`, and within a set, the list is sorted in ascending order by `id`.
set_id	String	An ID that identifies this set of chat badges. For example, Bits or Subscriber.
versions	Object[]	The list of chat badges in this set.
id	String	An ID that identifies this version of the badge. The ID can be any value. For example, for Bits, the ID is the Bits tier level, but for World of Warcraft, it could be Alliance or Horde.
image_url_1x	String	A URL to the small version (18px x 18px) of the badge.
image_url_2x	String	A URL to the medium version (36px x 36px) of the badge.
image_url_4x	String	A URL to the large version (72px x 72px) of the badge.
title	String	The title of the badge.
description	String	The description of the badge.
click_action	String	The action to take when clicking on the badge. Set to `null` if no action is specified.
click_url	String	The URL to navigate to when clicking on the badge. Set to `null` if no URL is specified.

Response Codes

Code	Description
200 OK	Successfully retrieved the broadcaster’s custom chat badges.
400 Bad Request	The broadcaster_id query parameter is required.
401 Unauthorized	The Authorization header is required and must specify a valid app access token or user access token. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

Get the list of custom chat badges that the BlueLava Twitch channel created.

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",
          "title": "cheer 1",
          "description": "cheer 1"
          "click_action": "visit_url",
          "click_url": "https://bits.twitch.tv"
        }
      ]
    },
    {
      "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",
          "title": "Subscriber",
          "description": "Subscriber",
          "click_action": "subscribe_to_channel",
          "click_url": null
        },
      ]
    }
  ]
}

Get Global Chat Badges

✎

Gets Twitch’s list of chat badges, which users may use in any channel’s chat room. For information about chat badges, see Twitch Chat Badges Guide.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

None

Response Body

Field	Type	Description
data	Object[]	The list of chat badges. The list is sorted in ascending order by `set_id`, and within a set, the list is sorted in ascending order by `id`.
set_id	String	An ID that identifies this set of chat badges. For example, Bits or Subscriber.
versions	Object[]	The list of chat badges in this set.
id	String	An ID that identifies this version of the badge. The ID can be any value. For example, for Bits, the ID is the Bits tier level, but for World of Warcraft, it could be Alliance or Horde.
image_url_1x	String	A URL to the small version (18px x 18px) of the badge.
image_url_2x	String	A URL to the medium version (36px x 36px) of the badge.
image_url_4x	String	A URL to the large version (72px x 72px) of the badge.
title	String	The title of the badge.
description	String	The description of the badge.
click_action	String	The action to take when clicking on the badge. Set to `null` if no action is specified.
click_url	String	The URL to navigate to when clicking on the badge. Set to `null` if no URL is specified.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of global chat badges.
401 Unauthorized	The Authorization header is required and must specify a valid app access token or user access token. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

Gets the list of 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",
          "title": "VIP",
          "description": "VIP",
          "click_action": "visit_url",
          "click_url": "https://help.twitch.tv/customer/en/portal/articles/659115-twitch-chat-badges-guide"
        }
      ]
    },
    ...
  ]
}

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 or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose chat settings you want to get.
moderator_id	String	No	The ID of the broadcaster or one of the broadcaster’s moderators. This field is required only if you want to include the `non_moderator_chat_delay` and `non_moderator_chat_delay_duration` settings in the response. If you specify this field, this ID must match the user ID in the user access token.

Response Body

Field	Type	Description
data	Object[]	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 chat messages may contain only emotes; otherwise, false.
follower_mode	Boolean	A Boolean value that determines whether the broadcaster restricts the chat room to followers only. Is true if the broadcaster restricts the chat room to followers only; otherwise, false. See the `follower_mode_duration` field for how long users must follow the broadcaster before being able to participate in the chat room.
follower_mode_duration	Integer	The length of time, in minutes, that users must follow the broadcaster before being able to participate in the chat room. 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. See the `non_moderator_chat_delay_duration` field for the length of the delay. Is true if the broadcaster applies a delay; otherwise, 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.
non_moderator_chat_delay_duration	Integer	The amount of time, in seconds, that messages are delayed before appearing in chat. 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 the `slow_mode_wait_time` field for the delay.
slow_mode_wait_time	Integer	The amount of time, in seconds, that users must wait between sending messages. 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 may 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	Description
200 OK	Successfully retrieved the broadcaster’s chat settings.
400 Bad Request	The broadcaster_id query parameter is required.
401 Unauthorized	The Authorization header is required and must specify a valid app access token or user access token. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.

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

Get Shared Chat Session

✎

NEW Retrieves the active shared chat session for a channel.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/shared_chat/session

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The User ID of the channel broadcaster.

Response Body

Field	Type	Description
data	Object[]
session_id	String	The unique identifier for the shared chat session.
host_broadcaster_id	String	The User ID of the host channel.
participants	Object[]	The list of participants in the session.
broadcaster_id	String	The User ID of the participant channel.
created_at	String	The UTC date and time (in RFC3339 format) for when the session was created.
updated_at	String	The UTC date and time (in RFC3339 format) for when the session was last updated.

Response Codes

Code	Description
200 OK	Successfully retrieved the shared chat session. Returns an empty array if the broadcaster_id in the request isn’t in a shared chat session.
400 Bad Request	The ID in the `broadcaster_id` query parameter is not valid.
401 Unauthorized	The OAuth token is not valid. The Authorization header is required and must contain a user access token.
500 Internal Error	Internal Server Error.

Example Request

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

Example Response

{
  "data": [
    {
      "session_id": "359bce59-fa4e-41a5-bd6f-9bc0c8360485",
      "host_broadcaster_id": “198704263”,
      "participants": [{
          "broadcaster_id": “198704263”
      }, {
          "broadcaster_id": “487263401”
      }],
      "created_at": "2024-09-29T19:45:37Z",
      "updated_at": "2024-09-29T19:45:37Z"
    }
  ]
}

Get User Emotes

✎

NEW Retrieves emotes available to the user across all channels.

Authorization

Requires a user access token that includes the user:read:emotes scope.
Query parameter user_id must match the user_id in the user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
user_id	String	Yes	The ID of the user. This ID must match the user ID in the user access token.
after	String	No	The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value.
broadcaster_id	String	No	The User ID of a broadcaster you wish to get follower emotes of. Using this query parameter will guarantee inclusion of the broadcaster’s follower emotes in the response body. Note: If the user specified in `user_id` is subscribed to the broadcaster specified, their follower emotes will appear in the response body regardless if this query parameter is used.

Response Body

Field	Type	Description
data	Object[]
id	String	An ID that uniquely identifies this emote.
name	String	The User ID of broadcaster whose channel is receiving the unban request.
emote_type	String	The type of emote. The possible values are: none — No emote type was assigned to this emote. bitstier — A Bits tier emote. follower — A follower emote. subscriptions — A subscriber emote. channelpoints — An emote granted by using channel points. rewards — An emote granted to the user through a special event. hypetrain — An emote granted for participation in a Hype Train. prime — An emote granted for linking an Amazon Prime account. turbo — An emote granted for having Twitch Turbo. smilies — Emoticons supported by Twitch. globals — An emote accessible by everyone. owl2019 — Emotes related to Overwatch League 2019. twofactor — Emotes granted by enabling two-factor authentication on an account. limitedtime — Emotes that were granted for only a limited time.
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[]	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 the emote is available as a static PNG and an animated GIF, the array contains static and animated. animated — An animated GIF is available for this emote. static — A static PNG file is available for this emote.
scale	String[]	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. 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[]	The background themes that the emote is available in. dark light
template	String	A templated URL. Uses the values from the id, format, scale, and theme_mode fields 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.
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. For more information about pagination support, see Twitch API Guide - Pagination.
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	Description
200 OK	Successfully retrieved the emotes.
400 Bad Request	The user_id query parameter is required. The ID in the user_id query parameter is not valid.
401 Unauthorized	The ID in user_id must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the user:read:emotes scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

curl -X GET 'https://api.twitch.tv/helix/chat/emotes/user?user_id=123456' \
-H 'Authorization: Bearer kpvy3cjboyptmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0nyan9c87zr6t'

Example Response

{
  "data": [
    {
      "emote_set_id": "",
      "emote_type": "hypetrain",
      "format": [
        "static"
      ],
      "id": "304420818",
      "name": "HypeLol",
      "owner_id": "477339272",
      "scale": [
        "1.0",
        "2.0",
        "3.0"
      ],
      "theme_mode": [
        "light",
        "dark"
      ]
    }
  ],
  "template": "https://static-cdn.jtvnw.net/emoticons/v2/{{id}}/{{format}}/{{theme_mode}}/{{scale}}",
  "pagination": {
    "cursor": "eyJiIjpudWxsLJxhIjoiIn0gf5"
  }
}

Update Chat Settings

✎

Updates the broadcaster’s chat settings.

Authorization

Requires a user access token that includes the moderator:manage:chat_settings scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose chat settings you want to update.
moderator_id	String	Yes	The ID of a user that has permission to moderate the broadcaster’s chat room, or the broadcaster’s ID if they’re making the update. This ID must match the user ID in the user access token.

Request Body

All fields are optional. Specify only those fields that you want to update.

To set the slow_mode_wait_time or follower_mode_duration field to its default value, set the corresponding slow_mode or follower_mode field to true (and don’t include the slow_mode_wait_time or follower_mode_duration field).

To set the slow_mode_wait_time, follower_mode_duration, or non_moderator_chat_delay_duration field’s value, you must set the corresponding slow_mode, follower_mode, or non_moderator_chat_delay field to true.

To remove the slow_mode_wait_time, follower_mode_duration, or non_moderator_chat_delay_duration field’s value, set the corresponding slow_mode, follower_mode, or non_moderator_chat_delay field to false (and don’t include the slow_mode_wait_time, follower_mode_duration, or non_moderator_chat_delay_duration field).

Field	Type	Description
emote_mode	Boolean	A Boolean value that determines whether chat messages must contain only emotes. Set to true if only emotes are allowed; otherwise, false. The default is false.
follower_mode	Boolean	A Boolean value that determines whether the broadcaster restricts the chat room to followers only. Set to true if the broadcaster restricts the chat room to followers only; otherwise, false. The default is true. To specify how long users must follow the broadcaster before being able to participate in the chat room, see the `follower_mode_duration` field.
follower_mode_duration	Integer	The length of time, in minutes, that users must follow the broadcaster before being able to participate in the chat room. Set only if `follower_mode` is true. Possible values are: 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. The default is false. To specify the length of the delay, see the `non_moderator_chat_delay_duration` field.
non_moderator_chat_delay_duration	Integer	The amount of time, in seconds, that messages are delayed before appearing in chat. Set only if `non_moderator_chat_delay` is true. Possible values are: 2 — 2 second delay (recommended) 4 — 4 second delay 6 — 6 second 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 between messages; otherwise, false. The default is false. To specify the delay, see the `slow_mode_wait_time` field.
slow_mode_wait_time	Integer	The amount of time, in seconds, that users must wait between sending messages. Set only if `slow_mode` is true. Possible values are: 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 may talk in the chat room. Set to true if the broadcaster restricts the chat room to subscribers only; otherwise, false. The 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 allows only unique messages; otherwise, false. The default is false.

Response Body

Field	Type	Description
data	Object[]	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 chat messages may contain only emotes; otherwise, false.
follower_mode	Boolean	A Boolean value that determines whether the broadcaster restricts the chat room to followers only. Is true if the broadcaster restricts the chat room to followers only; otherwise, false. See the `follower_mode_duration` field for how long users must follow the broadcaster before being able to participate in the chat room.
follower_mode_duration	Integer	The length of time, in minutes, that users must follow the broadcaster before being able to participate in the chat room. 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. See the `non_moderator_chat_delay_duration` field for the length of the delay. Is true if the broadcaster applies a delay; otherwise, false.
non_moderator_chat_delay_duration	Integer	The amount of time, in seconds, that messages are delayed before appearing in chat. 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 the `slow_mode_wait_time` field for the delay.
slow_mode_wait_time	Integer	The amount of time, in seconds, that users must wait between sending messages. 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 may 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	Description
200 OK	Successfully updated the broadcaster’s chat settings.
400 Bad Request	The broadcaster_id query parameter is required. The moderator_id query parameter is required. If slow_mode is true, the `slow_mode_wait_time` field must be set to a valid value. If `follower_mode` is true, the `follower_mode_duration` field must be set to a valid value. If `non_moderator_chat_delay` is true, the `non_moderator_chat_delay_duration` field must be set to a valid value.
401 Unauthorized	The ID in the moderator_id query parameter must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the moderator:manage:chat_settings scope. The access token is not valid. The ID in the Client-Id header must match the client ID in the access token.
403 Forbidden	The user in the moderator_id query parameter must have moderator privileges in the broadcaster's channel.

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

✎

Sends an announcement to the broadcaster’s chat room.

Authorization

Requires a user access token that includes the moderator:manage:announcements scope.

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, or the broadcaster’s ID if they’re sending the announcement. This ID must match the user ID in the user access token.

Request Body

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	Description
204 No Content	Successfully sent the announcement.
400 Bad Request	The `message` field in the request's body is required. The `message` field may not contain an empty string. The string in the `message` field failed review. The specified color is not valid.
401 Unauthorized	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.

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

Send a Shoutout

✎

Sends a Shoutout to the specified broadcaster. Typically, you send Shoutouts when you or one of your moderators notice another broadcaster in your chat, the other broadcaster is coming up in conversation, or after they raid your broadcast.

Twitch’s Shoutout feature is a great way for you to show support for other broadcasters and help them grow. Viewers who do not follow the other broadcaster will see a pop-up Follow button in your chat that they can click to follow the other broadcaster. Learn More

Rate Limits The broadcaster may send a Shoutout once every 2 minutes. They may send the same broadcaster a Shoutout once every 60 minutes.

To receive notifications when a Shoutout is sent or received, subscribe to the channel.shoutout.create and channel.shoutout.receive subscription types. The channel.shoutout.create event includes cooldown periods that indicate when the broadcaster may send another Shoutout without exceeding the endpoint’s rate limit.

Authorization

Requires a user access token that includes the moderator:manage:shoutouts scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
from_broadcaster_id	String	Yes	The ID of the broadcaster that’s sending the Shoutout.
to_broadcaster_id	String	Yes	The ID of the broadcaster that’s receiving the Shoutout.
moderator_id	String	Yes	The ID of the broadcaster or a user that is one of the broadcaster’s moderators. This ID must match the user ID in the access token.

Response Body

None

Response Codes

Code	Description
204 No Content	Successfully sent the specified broadcaster a Shoutout.
400 Bad Request	The from_broadcaster_id query parameter is required. The ID in the from_broadcaster_id query parameter is not valid. The to_broadcaster_id query parameter is required. The ID in the to_broadcaster_id query parameter is not valid. The broadcaster may not give themselves a Shoutout. The broadcaster is not streaming live or does not have one or more viewers.
401 Unauthorized	The ID in moderator_id must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the moderator:manage:shoutouts scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in moderator_id is not one of the broadcaster's moderators. The broadcaster may not send the specified broadcaster a Shoutout.
429 Too Many Requests	The broadcaster exceeded the number of Shoutouts they may send within a given window. See the endpoint's Rate Limits. The broadcaster exceeded the number of Shoutouts they may send the same broadcaster within a given window. See the endpoint's Rate Limits.

Example Request

curl -X POST 'https://api.twitch.tv/helix/chat/shoutouts?from_broadcaster_id=12345&to_broadcaster_id=626262&moderator_id=98765' \
-H 'Authorization: Bearer kpvy3cjboyptmdkiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfnys0nyan9c87zr6t'

Send Chat Message

✎

NEW Sends a message to the broadcaster’s chat room.

Authorization

Requires an app access token or user access token that includes the user:write:chat scope. If app access token used, then additionally requires user:bot scope from chatting user, and either channel:bot scope from broadcaster or moderator status.

URL

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

Request Body

Field	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose chat room the message will be sent to.
sender_id	String	Yes	The ID of the user sending the message. This ID must match the user ID in the user access token.
message	String	Yes	The message to send. The message is limited to a maximum of 500 characters. Chat messages can also include emoticons. To include emoticons, use the name of the emote. The names are case sensitive. Don’t include colons around the name (e.g., :bleedPurple:). If Twitch recognizes the name, Twitch converts the name to the emote before writing the chat message to the chat room
reply_parent_message_id	String	No	The ID of the chat message being replied to.

Response Body

Field	Type	Description
data	Object[]
message_id	String	The message id for the message that was sent.
is_sent	Boolean	If the message passed all checks and was sent.
drop_reason	Object	The reason the message was dropped, if any.
code	String	Code for why the message was dropped.
message	String	Message for why the message was dropped.

Response Codes

Code	Description
200 OK	Successfully sent the specified broadcaster a message.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the broadcaster_id query parameter is not valid. The sender_id query parameter is required. The ID in the sender_id query parameter is not valid. The text query parameter is required. The ID in the reply_parent_message_id query parameter is not valid.
401 Unauthenticated	The ID in the user_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 user:write:chat scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The sender is not permitted to send chat messages to the broadcaster’s chat room.
422 Unprocessable Entity	The message is too large.

Example Request

curl -X POST 'https://api.twitch.tv/helix/chat/messages' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
-d '{
  "broadcaster_id": "12826",
  "sender_id": "141981764",
  "message": "Hello, world! twitchdevHype"
}'

Example Response

{
  "data": [
    {
      "message_id": "abc-123-def",
      "is_sent": true
    }
  ]
}

Get User Chat Color

✎

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 username 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 API ignores duplicate IDs and IDs that weren’t found.

Response Body

Field	Type	Description
data	Object[]	The list of users and the color code they use for their name.
user_id	String	An ID that uniquely identifies 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	Description
200 OK	Successfully retrieved the chat color used by the specified users.
400 Bad Request	The ID in the user_id query parameter is not valid.
401 Unauthorized	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 chat color code used by the specified users.

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

✎

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.

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. This ID must match the user ID in the access token.
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	Description
204 No Content	Successfully updated the user's chat color.
400 Bad Request	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	The Authorization header is required and must contain a user access token. The user access token must include 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 from the broadcaster’s stream.

This API captures up to 90 seconds of the broadcaster’s stream. The 90 seconds spans the point in the stream from when you called the API. For example, if you call the API at the 4:00 minute mark, the API captures from approximately the 3:35 mark to approximately the 4:05 minute mark. Twitch tries its best to capture 90 seconds of the stream, but the actual length may be less. This may occur if you begin capturing the clip near the beginning or end of the stream.

By default, Twitch publishes up to the last 30 seconds of the 90 seconds window and provides a default title for the clip. To specify the title and the portion of the 90 seconds window that’s used for the clip, use the URL in the response’s edit_url field. You can specify a clip that’s from 5 seconds to 60 seconds in length. The URL is valid for up to 24 hours or until the clip is published, whichever comes first.

Creating a clip is an asynchronous process that can take a short amount of time to complete. To determine whether the clip was successfully created, call Get Clips using the clip ID that this request returned. If Get Clips returns the clip, the clip was successfully created. If after 15 seconds Get Clips hasn’t returned the clip, assume it failed.

Authorization

Requires a user access token that includes the clips:edit scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose stream you want to create a clip from.
has_delay	Boolean	No	A Boolean value that determines whether the API captures the clip at the moment the viewer requests it or after a delay. If false (default), Twitch captures the clip at the moment the viewer requests it (this is the same clip experience as the Twitch UX). If true, Twitch adds a delay before capturing the clip (this basically shifts the capture window to the right slightly).

Response Body

Field	Type	Description
edit_url	String	A URL that you can use to edit the clip’s title, identify the part of the clip to publish, and publish the clip. Learn More The URL is valid for up to 24 hours or until the clip is published, whichever comes first.
id	String	An ID that uniquely identifies the clip.

Response Codes

Code	Description
202 Accepted	Successfully started the clip process.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the broadcaster_id query parameter was not found.
401 Unauthorized	The Authorization header is required and must specify user access token. The user access token must include the clips:edit scope. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.
403 Forbidden	The broadcaster has restricted the ability to capture clips to followers and/or subscribers only. The specified broadcaster has not enabled clips on their channel.
404 Not Found	The broadcaster in the broadcaster_id query parameter must be broadcasting live.

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 one or more video clips that were captured from streams. For information about clips, see How to use clips.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

The id, game_id, and broadcaster_id query parameters are mutually exclusive.

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	An ID that identifies the broadcaster whose video clips you want to get. Use this parameter to get clips that were captured from the broadcaster’s streams.
game_id	String	Yes	An ID that identifies the game whose clips you want to get. Use this parameter to get clips that were captured from streams that were playing this game.
id	String	Yes	An ID that identifies the clip to get. To specify more than one ID, include this parameter for each clip you want to get. For example, `id=foo&id=bar`. You may specify a maximum of 100 IDs. The API ignores duplicate IDs and IDs that aren’t found.
started_at	String	No	The start date used to filter clips. The API returns only clips within the start and end date window. Specify the date and time in RFC3339 format.
ended_at	String	No	The end date used to filter clips. If not specified, the time window is the start date plus one week. Specify the date and time in RFC3339 format.
first	Integer	No	The maximum number of clips to return per page in the response. The minimum page size is 1 clip per page and the maximum is 100. The default is 20.
before	String	No	The cursor used to get the previous page of results. The Pagination object in the response contains the cursor’s value. Read More
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
is_featured	Boolean	No	A Boolean value that determines whether the response includes featured clips. If true, returns only clips that are featured. If false, returns only clips that aren’t featured. All clips are returned if this parameter is not present.

Response Body

Field	Type	Description
data	Object[]	The list of video clips. For clips returned by game_id or broadcaster_id, the list is in descending order by view count. For lists returned by id, the list is in the same order as the input IDs.
id	String	An ID that uniquely identifies the clip.
url	String	A URL to the clip.
embed_url	String	A URL that you can use in an iframe to embed the clip (see Embedding Video and Clips).
broadcaster_id	String	An ID that identifies the broadcaster that the video was clipped from.
broadcaster_name	String	The broadcaster’s display name.
creator_id	String	An ID that identifies the user that created the clip.
creator_name	String	The user’s display name.
video_id	String	An ID that identifies the video that the clip came from. This field contains an empty string if the video is not available.
game_id	String	The ID of the game that was being played when the clip was created.
language	String	The ISO 639-1 two-letter language code that the broadcaster broadcasts in. For example, en for English. The value is other if the broadcaster uses a language that Twitch doesn’t support.
title	String	The title of the clip.
view_count	Integer	The number of times the clip has been viewed.
created_at	String	The date and time of when the clip was created. The date and time is in RFC3339 format.
thumbnail_url	String	A URL to a thumbnail image of the clip.
duration	float	The length of the clip, in seconds. Precision is 0.1.
vod_offset	Integer	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.
is_featured	Boolean	A Boolean value that indicates if the clip is featured or not.
pagination	Object	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. Set the request’s after or before query parameter to this value depending on whether you’re paging forwards or backwards.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of video clips.
400 Bad Request	The id or game_id or broadcaster_id query parameter is required. The id, game_id, and broadcaster_id query parameters are mutually exclusive; you may specify only one of them.
401 Unauthorized	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.
404 Not Found	The ID in game_id was not found.

Example Request

Gets a clip by ID.

curl -X GET 'https://api.twitch.tv/helix/clips?id=AwkwardHelplessSalamanderSwiftRage' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "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,
      "is_featured": false
    }
  ]
}

Example Request

Gets the broadcaster’s top 5 clips based on views.

curl -X GET 'https://api.twitch.tv/helix/clips?broadcaster_id=1234&first=5' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "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,
      "is_featured": true
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjoiIn0"
  }
}

Get Conduits

✎

NEW Gets the conduits for a client ID.

Authorization

Requires an app access token.

URL

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

Response Body

Parameter	Type	Description
data	Object[]	List of information about the client’s conduits.
id	String	Conduit ID.
shard_count	Integer	Number of shards associated with this conduit.

Response Codes

Code	Meaning
200 OK	Successfully retrieved conduits.
401 Unauthenticated	Authorization header required with an app access token.

Example Request

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

Example Response

{
  "data": [
    {
      "id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
      "shard_count": 15
    },
    {
      "id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
      "shard_count": 5
    }
  ]
}

Create Conduits

✎

NEW Creates a new conduit.

Authorization

Requires an app access token.

URL

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

Request Body

Parameter	Type	Required	Description
shard_count	Integer	Yes	The number of shards to create for this conduit.

Response Body

Parameter	Type	Description
data	Object[]	List of information about the client’s conduits.
id	String	Conduit ID.
shard_count	Integer	Number of shards created for this conduit.

Response Codes

Code	Meaning
200 OK	Conduit created.
400 Bad Request	Invalid shard count.
401 Unauthenticated	Authorization header required with an app access token.
429 Too Many Requests	Conduit limit reached.

Example Request

curl -X POST 'https://api.twitch.tv/helix/eventsub/conduits' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{"shard_count": 5}'

Example Response

{
  "data": [
    {
      "id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
      "shard_count": 5
    }
  ]
}

Update Conduits

✎

NEW Updates a conduit’s shard count. To delete shards, update the count to a lower number, and the shards above the count will be deleted. For example, if the existing shard count is 100, by resetting shard count to 50, shards 50-99 are disabled.

Authorization

Requires an app access token.

URL

PATCH https://api.twitch.tv/helix/eventsub/conduits

Request Body

Parameter	Type	Required	Description
id	String	Yes	Conduit ID.
shard_count	Integer	Yes	The new number of shards for this conduit.

Response Body

Parameter	Type	Description
data	Object[]	List of information about the client’s conduits.
id	String	Conduit ID.
shard_count	Integer	Number of shards associated with this conduit after the update.

Response Codes

Code	Meaning
200 OK	Conduit updated.
400 Bad Request	Invalid shard count The id query parameter is required.
401 Unauthenticated	Authorization header required with an app access token.
404 Not Found	Conduit not found. Conduit’s owner must match the client ID in the access token.

Example Request

curl -X PATCH 'https://api.twitch.tv/helix/eventsub/conduits' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "id":"bfcfc993-26b1-b876-44d9-afe75a379dac",
  "shard_count":5
}'

Example Response

{
  "data": [
    {
      "id": "bfcfc993-26b1-b876-44d9-afe75a379dac",
      "shard_count": 5
    }
  ]
}

Delete Conduit

✎

NEW Deletes a specified conduit. Note that it may take some time for Eventsub subscriptions on a deleted conduit to show as disabled when calling Get Eventsub Subscriptions.

Authorization

Requires an app access token.

URL

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

Request Query Parameters

Parameter	Type	Required	Description
id	String	Yes	Conduit ID.

Response Codes

Code	Meaning
204 No Content	Successfully deleted the conduit.
400 Bad Request	The id query parameter is required.
401 Unauthenticated	Authorization header required with an app access token.
404 Not Found	Conduit not found. Conduit’s owner must match the client ID in the access token.

Example Request

curl -X DELETE 'https://api.twitch.tv/helix/eventsub/conduits?id=bfcfc993-26b1-b876-44d9-afe75a379dac' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Get Conduit Shards

✎

NEW Gets a lists of all shards for a conduit.

Authorization

Requires an app access token.

URL

GET https://api.twitch.tv/helix/eventsub/conduits/shards

Request Query Parameters

Parameter	Type	Required	Description
conduit_id	String	Yes	Conduit ID.
status	String	No	Status to filter by.
after	String	No	The cursor used to get the next page of results. The pagination object in the response contains the cursor’s value.

Response Body

Parameter	Type	Description
data	Object[]	List of information about a conduit's shards.
id	String	Shard ID.
status	String	The shard status. The subscriber receives events only for enabled shards. Possible values are: enabled — The shard is enabled. webhook_callback_verification_pending — The shard 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. websocket_disconnected — The client closed the connection. websocket_failed_ping_pong — The client failed to respond to a ping message. websocket_received_inbound_traffic — The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message). websocket_internal_error — The Twitch WebSocket server experienced an unexpected error. websocket_network_timeout — The Twitch WebSocket server timed out writing the message to the client. websocket_network_error — The Twitch WebSocket server experienced a network error writing the message to the client. websocket_failed_to_reconnect - The client failed to reconnect to the Twitch WebSocket server within the required time after a Reconnect Message.
transport	Object	The transport details used to send the notifications.
method	String	The transport method. Possible values are: webhook websocket
callback	String	The callback URL where the notifications are sent. Included only if method is set to webhook.
session_id	String	An ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket.
connected_at	String	The UTC date and time that the WebSocket connection was established. Included only if method is set to websocket.
disconnected_at	String	The UTC date and time that the WebSocket connection was lost. Included only if method is set to websocket.
pagination	Object	Contains information used to page through a list of results. The object is empty if there are no more pages left to page through.
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 OK	Successfully retrieved shards.
400 Bad Request	The id query parameter is required.
401 Unauthenticated	Authorization header required with an app access token.
404 Not Found	Conduit not found. Conduit’s owner must match the client ID in the access token.

Example Request

curl -X GET 'https://api.twitch.tv/helix/eventsub/conduits/shards?conduit_id=bfcfc993-26b1-b876-44d9-afe75a379dac' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "0",
      "status": "enabled",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback.com"
      }
    },
    {
      "id": "1",
      "status": "webhook_callback_verification_pending",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback-2.com"
      }
    },
    {
      "id": "2",
      "status": "enabled",
      "transport": {
        "method": "websocket",
        "session_id": "9fd5164a-a958-4c60-b7f4-6a7202506ca0",
        "connected_at": "2020-11-10T14:32:18.730260295Z"
      }
    },
    {
      "id": "3",
      "status": "enabled",
      "transport": {
        "method": "websocket",
        "session_id": "238b4b08-13f1-4b8f-8d31-56665a7a9d9f",
        "connected_at": "2020-11-10T14:32:18.730260295Z"
      }
    },
    {
      "id": "4",
      "status": "websocket_disconnected",
      "transport": {
        "method": "websocket",
        "session_id": "ad1c9fc3-0d99-4eb7-8a04-8608e8ff9ec9",
        "connected_at": "2020-11-10T14:32:18.730260295Z",
        "disconnected_at": "2020-11-11T14:32:18.730260295Z"
      }
    }
  ],
  "pagination": {},
}

Update Conduit Shards

✎

NEW Updates shard(s) for a conduit.

NOTE: Shard IDs are indexed starting at 0, so a conduit with a shard_count of 5 will have shards with IDs 0 through 4.

Authorization

Requires an app access token.

URL

PATCH https://api.twitch.tv/helix/eventsub/conduits/shards

Request Body

Parameter	Type	Required	Description
conduit_id	String	Yes	Conduit ID.
shards	Object[]	Yes	List of shards to update.
id	String	Yes	Shard ID.
transport	Object	Yes	The transport details that you want Twitch to use when sending you notifications.
method	String	No	The transport method. Possible values are: webhook websocket
callback	String	No	The callback URL where the notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an event.Specify this field only if method is set to webhook.NOTE: Redirects are not followed.
secret	String	No	The secret used to verify the signature. The secret must be an ASCII string that’s a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.Specify this field only if method is set to webhook.
session_id	String	No	An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.Specify this field only if method is set to websocket.

Response Body

Parameter	Type	Description
data	Object[]	List of successful shard updates.
id	String	Shard ID.
status	String	The shard status. The subscriber receives events only for enabled shards. Possible values are: enabled — The shard is enabled. webhook_callback_verification_pending — The shard 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. websocket_disconnected — The client closed the connection. websocket_failed_ping_pong — The client failed to respond to a ping message. websocket_received_inbound_traffic — The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message). websocket_internal_error — The Twitch WebSocket server experienced an unexpected error. websocket_network_timeout — The Twitch WebSocket server timed out writing the message to the client. websocket_network_error — The Twitch WebSocket server experienced a network error writing the message to the client. websocket_failed_to_reconnect - The client failed to reconnect to the Twitch WebSocket server within the required time after a Reconnect Message.
transport	Object	The transport details used to send the notifications.
method	String	The transport method. Possible values are: webhook websocket
callback	String	The callback URL where the notifications are sent. Included only if method is set to webhook.
session_id	String	An ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket.
connected_at	String	The UTC date and time that the WebSocket connection was established. Included only if method is set to websocket.
disconnected_at	String	The UTC date and time that the WebSocket connection was lost. Included only if method is set to websocket.
errors	Object[]	List of unsuccessful updates.
id	String	Shard ID.
message	String	The error that occurred while updating the shard. Possible errors: The length of the string in the secret field is not valid. The URL in the transport's callback field is not valid. The URL must use the HTTPS protocol and the 443 port number. The value specified in the method field is not valid. The callback field is required if you specify the webhook transport method. The session_id field is required if you specify the WebSocket transport method. The websocket session is not connected. The shard id is outside of the conduit’s range.
code	String	Error codes used to represent a specific error condition while attempting to update shards.

Response Codes

Code	Meaning
202 Accepted	Successfully retrieved shards.
400 Bad Request	The id query parameter is required.
401 Unauthenticated	Authorization header required with an app access token.
404 Not Found	Conduit not found. Conduit’s owner must match the client ID in the access token.

Example Request

curl -X PATCH 'https://api.twitch.tv/helix/eventsub/conduits/shards' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "conduit_id":"bfcfc993-26b1-b876-44d9-afe75a379dac",
  "shards": [{
    "id": "0",
    "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback.com",
        "secret": "s3cre7"
    }
  },
  {
    "id": "1",
    "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback-2.com",
        "secret": "s3cre7"
    }
  },
  {
    "id": "3",
    "transport":{
        "method": "webhook",
        "callback": "https://this-is-a-callback-3.com"
        "secret": "s3cre7"
    }
  }]
}'

Example Response

{
  "data": [
    {
      "id": "0",
      "status": "enabled",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback.com"
      }
    },
    {
      "id": "1",
      "status": "webhook_callback_verification_pending",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback-2.com"
      }
    }
  ],
  "errors": [
    {
      "id": "3",
      "message": "The shard id is outside the conduit's range",
      "code": "invalid_parameter"
    }
  ]
}

Get Content Classification Labels

✎

Gets information about Twitch content classification labels.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
locale	String	No	Locale for the Content Classification Labels. You may specify a maximum of 1 locale. Default: `“en-US”` Supported locales: `"bg-BG", "cs-CZ", "da-DK", "da-DK", "de-DE", "el-GR", "en-GB", "en-US", "es-ES", "es-MX", "fi-FI", "fr-FR", "hu-HU", "it-IT", "ja-JP", "ko-KR", "nl-NL", "no-NO", "pl-PL", "pt-BT", "pt-PT", "ro-RO", "ru-RU", "sk-SK", "sv-SE", "th-TH", "tr-TR", "vi-VN", "zh-CN", "zh-TW"`

Response Body

Field	Type	Description
data	Object[]	A list that contains information about the available content classification labels.
content_classification_labels	Label[]	The list of CCLs available.
id	String	Unique identifier for the CCL.
description	String	Localized description of the CCL.
name	String	Localized name of the CCL.

Example Request

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

Example Response

{
  "data": [
    {
      "id": "DebatedSocialIssuesAndPolitics",
      "description": "Discussions or debates about politics or sensitive social issues such as elections, civic integrity, military conflict, and civil rights in a polarizing manner.",
      "name": "Politics and Sensitive Social Issues"
    },
    {
      "id": "DrugsIntoxication",
      "description": "Excessive tobacco glorification or promotion, any marijuana consumption/use, legal drug and alcohol induced intoxication, discussions of illegal drugs.",
      "name": "Drugs, Intoxication, or Excessive Tobacco Use"
    },
    {
      "id": "Gambling",
      "description": "Participating in online or in-person gambling, poker or fantasy sports, that involve the exchange of real money.",
      "name": "Gambling"
    },
    {
      "id": "MatureGame",
      "description": "Games that are rated Mature or less suitable for a younger audience.",
      "name": "Mature-rated game"
    },
    {
      "id": "ProfanityVulgarity",
      "description": "Prolonged, and repeated use of obscenities, profanities, and vulgarities, especially as a regular part of speech.",
      "name": "Significant Profanity or Vulgarity"
    },
    {
      "id": "SexualThemes",
      "description": "Content that focuses on sexualized physical attributes and activities, sexual topics, or experiences.",
      "name": "Sexual Themes"
    },
    {
      "id": "ViolentGraphic",
      "description": "Simulations and/or depictions of realistic violence, gore, extreme injury, or death.",
      "name": "Violent and Graphic Depictions"
    }
  ]
}

Get Drops Entitlements

✎

Gets an organization’s list of entitlements that have been granted to a game, a user, or both.

NOTE: Entitlements returned in the response body data are not guaranteed to be sorted by any field returned by the API. To retrieve CLAIMED or FULFILLED entitlements, use the fulfillment_status query parameter to filter results. To retrieve entitlements for a specific game, use the game_id query parameter to filter results.

The following table identifies the request parameters that you may specify based on the type of access token used.

Access token type	Parameter	Description
App	None	If you don’t specify request parameters, the request returns all entitlements that your organization owns.
App	user_id	The request returns all entitlements for any game that the organization granted to the specified user.
App	user_id, game_id	The request returns all entitlements that the specified game granted to the specified user.
App	game_id	The request returns all entitlements that the specified game granted to all entitled users.
User	None	If you don’t specify request parameters, the request returns all entitlements for any game that the organization granted to the user identified in the access token.
User	user_id	Invalid.
User	user_id, game_id	Invalid.
User	game_id	The request returns all entitlements that the specified game granted to the user identified in the access token.

Authorization

Requires an app access token or user access token. The client ID in the access token must own the game.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
id	String	No	An ID that identifies the entitlement to get. Include this parameter for each entitlement you want to get. For example, `id=1234&id=5678`. You may specify a maximum of 100 IDs.
user_id	String	No	An ID that identifies a user that was granted entitlements.
game_id	String	No	An ID that identifies a game that offered entitlements.
fulfillment_status	String	No	The entitlement’s fulfillment status. Used to filter the list to only those with the specified status. Possible values are: CLAIMED FULFILLED
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
first	Integer	No	The maximum number of entitlements to return per page in the response. The minimum page size is 1 entitlement per page and the maximum is 1000. The default is 20.

Response Body

Field	Type	Description
data	Object[]	The list of entitlements.
id	String	An ID that identifies the entitlement.
benefit_id	String	An ID that identifies the benefit (reward).
timestamp	String	The UTC date and time (in RFC3339 format) of when the entitlement was granted.
user_id	String	An ID that identifies the user who was granted the entitlement.
game_id	String	An ID that identifies the game the user was playing when the reward was entitled.
fulfillment_status	String	The entitlement’s fulfillment status. Possible values are: CLAIMED FULFILLED
last_updated	String	The UTC date and time (in RFC3339 format) of when the entitlement was last updated.
pagination	Object	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. Set the request’s after query parameter to this value to page forward through the results.

Response Codes

Code	Description
200 OK	Successfully retrieved the entitlements.
400 Bad Request	The value in the fulfillment_status query parameter is not valid. The ID in the user_id query parameter must match the user ID in the user access token. The client in the access token is not associated with a known organization. The owner of the client in the access token is not a member of the organization.
401 Unauthorized	The ID in the Client-Id header must match the Client ID in the access token. The Authorization header is required and must specify an app access token or user access token. The access token is not valid.
403 Fobidden	The organization associated with the client in the access token must own the game specified in the game_id query parameter. The organization associated with the client in the access token must own the entitlements specified in the id query parameter.
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",
      "last_updated": "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",
      "last_updated": "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",
      "last_updated": "2019-01-28T04:17:53.325Z"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudW..."
  }
}

Update Drops Entitlements

✎

Updates the Drop entitlement’s fulfillment status.

The following table identifies which entitlements are updated based on the type of access token used.

Access token type	Data that’s updated
App	Updates all entitlements with benefits owned by the organization in the access token.
User	Updates all entitlements owned by the user in the access token and where the benefits are owned by the organization in the access token.

Authorization

Requires an app access token or user access token. The client ID in the access token must own the game.

URL

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

Request Body

Field	Type	Required?	Description
entitlement_ids	String[]	No	A list of IDs that identify the entitlements to update. You may specify a maximum of 100 IDs.
fulfillment_status	String	No	The fulfillment status to set the entitlements to. Possible values are: CLAIMED — The user claimed the benefit. FULFILLED — The developer granted the benefit that the user claimed.

Response Body

Field	Type	Description
data	Object[]	A list that indicates which entitlements were successfully updated and those that weren’t.
status	String	A string that indicates whether the status of the entitlements in the `ids` field were successfully updated. Possible values are: INVALID_ID — The entitlement IDs in the `ids` field are not valid. NOT_FOUND — The entitlement IDs in the `ids` field were not found. SUCCESS — The status of the entitlements in the `ids` field were successfully updated. UNAUTHORIZED — The user or organization identified by the user access token is not authorized to update the entitlements. UPDATE_FAILED — The update failed. These are considered transient errors and the request should be retried later.
ids	String[]	The list of entitlements that the status in the `status` field applies to.

Response Codes

Code	Description
200 OK	Successfully requested the updates. Check the response to determine which updates succeeded.
400 Bad Request	The value in the `fulfillment_status` field is not valid. The client in the access token is not associated with a known organization. The owner of the client in the access token is not a member of the organization.
401 Unauthorized	The Authorization header is required and must specify an app access token or user access token. The access token is not valid. The ID in the Client-Id header must match the Client ID in the access token.
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"
      ]
    }
  ]
}

Get Extension Configuration Segment

✎

Gets the specified configuration segment from the specified extension.

Rate Limits: You may retrieve each segment a maximum of 20 times per minute.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role, user_id, and exp fields (see JWT Schema). The role field must be set to external.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	No	The ID of the broadcaster that installed the extension. 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	Yes	The ID of the extension that contains the configuration segment you want to get.
segment	String	Yes	The type of configuration segment to get. Possible case-sensitive 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`. Ignores duplicate segments.

Response Body

Field	Type	Description
data	Object[]	The list of requested configuration segments. The list is returned in the same order that you specified the list of segments in the request.
segment	String	The type of segment. Possible values are: broadcaster developer global
broadcaster_id	String	The ID of the broadcaster that installed 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-text string or a string-encoded JSON object.
version	String	The version number that identifies this definition of the segment’s data.

Response Codes

Code	Description
200 OK	Successfully retrieved the configurations.
400 Bad Request	The extension_id query parameter is required. The value in the segment query parameter is not valid. The broadcaster_id query parameter is required if the segment query parameter is set to broadcaster or developer.
401 Unauthorized	The Authorization header is required and must specify a JWT token. The JWT token is not valid. The Client-Id header is required.
429 Too many requests	The app exceeded the number of requests that it may make per minute. See Rate Limits above.

Example Request

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

✎

Updates a configuration segment. The segment is limited to 5 KB. Extensions that are active on a channel do not receive the updated configuration.

Rate Limits: You may update the configuration a maximum of 20 times per minute.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role, user_id, and exp fields (see JWT Schema). The role field must be set to external.

URL

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

Request Body

Field	Type	Required?	Description
extension_id	String	Yes	The ID of the extension to update.
segment	String	Yes	The configuration segment to update. Possible case-sensitive values are: broadcaster developer global
broadcaster_id	String	No	The ID of the broadcaster that installed the extension. Include this field only if the `segment` is set to developer or broadcaster.
content	String	No	The contents of the segment. This string may be a plain-text string or a string-encoded JSON object.
version	String	No	The version number that identifies this definition of the segment’s data. If not specified, the latest definition is updated.

Response Codes

Code	Description
204 No Content	Successfully updated the configuration.
400 Bad Request	The `broadcaster_id` field is required if `segment` is set to developer or broadcaster.
401 Unauthorized	The Authorization header is required and must specify a JWT token. The JWT token is not valid. The Client-Id header is required.

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

Set Extension Required Configuration

✎

Updates the extension’s required_configuration string. Use this endpoint if your extension requires the broadcaster to configure the extension before activating it (to require configuration, you must select Custom/My Own Service in Extension Capabilities). For more information, see Required Configurations and Setting Required Configuration.

Authorization

Requires a signed JSON Web Token (JWT) created by an EBS. For signing requirements, see Signing the JWT. The signed JWT must include the role, user_id, and exp fields (see JWT Schema). Set the role field to external and the user_id field to the ID of the user that owns the extension.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that installed the extension on their channel.

Request Body

Parameter	Type	Required?	Description
extension_id	String	Yes	The ID of the extension to update.
extension_version	String	Yes	The version of the extension to update.
required_configuration	String	Yes	The required_configuration string to use with the extension.

Response Codes

Code	Description
204 Not Found	Successfully updated the extension’s required_configuration string.
400 Bad Request	The broadcaster_id query parameter is required. The `extension_id` field is required. The `extension_version` field is required. The `required_configuration` field is required.
401 Unauthorized	The Authorization header is required and must specify a JWT token. The JWT token is not valid. The Client-Id header is required.

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

Send Extension PubSub Message

✎

Sends a message to one or more viewers. You can send messages to a specific channel or to all channels where your extension is active. This endpoint uses the same mechanism as the send JavaScript helper function used to send messages.

Rate Limits: You may send a maximum of 100 messages per minute per combination of extension client ID and broadcaster ID.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role, user_id, and exp fields (see JWT Schema) along with the channel_id and pubsub_perms fields. The role field must be set to external.

To send the message to a specific channel, set the channel_id field in the JWT to the channel’s ID and set the pubsub_perms.send array to broadcast.

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

To send the message to all channels on which your extension is active, set the channel_id field to all and set the pubsub_perms.send array to global.

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

URL

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

Request Body

Field	Type	Required?	Description
target	String[]	Yes	The target of the message. Possible values are: broadcast global whisper-<user-id> If `is_global_broadcast` is true, you must set this field to global. The broadcast and global values are mutually exclusive; specify only one of them.
broadcaster_id	string	Yes	The ID of the broadcaster to send the message to. Don’t include this field if `is_global_broadcast` is set to true.
is_global_broadcast	Boolean	No	A Boolean value that determines whether the message should be sent to all channels where your extension is active. Set to true if the message should be sent to all channels. The default is false.
message	String	Yes	The message to send. The message can be a plain-text string or a string-encoded JSON object. The message is limited to a maximum of 5 KB.

Response Codes

Code	Description
204 No Content	Successfully sent the message.
400 Bad Request	The `broadcaster_id` field in the request's body may only be set if the `is_global_broadcast` field is set to false.
401 Unauthorized	The Authorization header is required and must specify a JWT token. The JWT token is not valid. The Client-Id header is required.
422 Unprocessable Entity	The message is too large.

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

Get Extension Live Channels

✎

Gets a list of broadcasters that are streaming live and have installed or activated the extension.

It may take a few minutes for the list to include or remove broadcasters that have recently gone live or stopped broadcasting.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
extension_id	String	Yes	The ID of the extension to get. Returns the list of broadcasters that are live and that have installed or activated this extension.
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 items per page. The default is 20.
after	String	No	The cursor used to get the next page of results. The `pagination` field in the response contains the cursor’s value. Read More

Response Body

Field	Type	Description
data	Object[]	The list of broadcasters that are streaming live and that have installed or activated the extension.
broadcaster_id	String	The ID of the broadcaster that is streaming live and has installed or activated the extension.
broadcaster_name	String	The broadcaster’s display name.
game_name	String	The name of the category or game being streamed.
game_id	String	The ID of the category or game being streamed.
title	String	The title of the broadcaster’s stream. May be an empty string if not specified.
pagination	String	This field contains the cursor used to page through the results. The field is empty if there are no more pages left to page through. Note that this field is a string compared to other endpoints that use a Pagination object. Read More

Response Codes

Code	Description
200 OK	Successfully retrieved the list of broadcasters.
400 Bad Request	The extension_id query parameter is required. The pagination cursor is not valid.
401 Unauthorized	The Authorization header is required and must specify an app access token or user access token. The access token is not valid. The ID in the Client-Id header must match the client ID in the access token.
404 Not Found	The extension specified in the extension_id query parameter was not found or it's not being used in a live stream.

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

✎

Gets an extension’s list of shared secrets.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role, user_id, and exp fields (see JWT Schema). The role field must be set to external.

URL

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

Request Query Paramters

Parameter	Type	Required?	Description
extension_id	String	Yes	The ID of the extension whose shared secrets you want to get.

Response Body

Field	Type	Description
data	Object[]	The list of shared secrets that the extension created.
format_version	Integer	The version number that identifies this definition of the secret’s data.
secrets	Object[]	The list of secrets.
content	String	The raw secret that you use with JWT encoding.
active_at	String	The UTC date and time (in RFC3339 format) that you may begin using this secret to sign a JWT.
expires_at	String	The UTC date and time (in RFC3339 format) that you must stop using this secret to decode a JWT.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of secrets.
400 Bad Request	The extension_id query parameter is required.
401 Unauthorized	The Authorization header is required and must specify a JWT token. The JWT token is not valid. The Client-Id header is required.

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 shared secret used to sign and verify JWT tokens. Creating a new secret removes the current secrets from service. Use this function only when you are ready to use the new secret it returns.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role, user_id, and exp fields (see JWT Schema). The role field must be set to external.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
extension_id	String	Yes	The ID of the extension to apply the shared secret to.
delay	Integer	No	The amount of time, in seconds, to delay activating the secret. The delay should provide enough time for instances of the extension to gracefully switch over to the new secret. The minimum delay is 300 seconds (5 minutes). The default is 300 seconds.

Response Body

Field	Type	Description
data	Object[]	A list that contains the newly added secrets.
format_version	Integer	The version number that identifies this definition of the secret’s data.
secrets	Object[]	The list of secrets.
content	String	The raw secret that you use with JWT encoding.
active_at	String	The UTC date and time (in RFC3339 format) that you may begin using this secret to sign a JWT.
expires_at	String	The UTC date and time (in RFC3339 format) that you must stop using this secret to decode a JWT.

Response Codes

Code	Description
200 OK	Successfully created the new secret.
400 Bad Request	The extension_id query parameter is required. The delay specified in the delay query parameter is too short.
401 Unauthorized	The Authorization header is required and must specify a JWT token. The JWT token is not valid. The Client-Id header is required.

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 message to the specified broadcaster’s chat room. The extension’s name is used as the username for the message in the chat room. To send a chat message, your extension must enable Chat Capabilities (under your extension’s Capabilities tab).

Rate Limits: You may send a maximum of 12 messages per minute per channel.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role and user_id fields (see JWT Schema). The role field must be set to external.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that has activated the extension.

Request Body

Field	Type	Required?	Description
text	String	Yes	The message. The message may contain a maximum of 280 characters.
extension_id	String	Yes	The ID of the extension that’s sending the chat message.
extension_version	String	Yes	The extension’s version number.

Response Codes

Code	Description
204 No Content	Successfully sent the chat message.
400 Bad Request	The broadcaster_id query parameter is required. The `extension_id` field in the request's body is required. The `extension_version` field in the request's body is required. The `text` field in the request's body is required. The message is too long.
401 Unauthorized	The Authorization header is required and must specify a JWT token. The ID in the broadcaster_id query parameter must match the `channel_id` claim in the JWT. The JWT token is not valid. The Client-Id header is required.

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

Get Extensions

✎

Gets information about an extension.

Authorization

Requires a signed JSON Web Token (JWT) created by an Extension Backend Service (EBS). For signing requirements, see Signing the JWT. The signed JWT must include the role field (see JWT Schema), and the role field must be set to external.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
extension_id	String	Yes	The ID of the extension to get.
extension_version	String	No	The version of the extension to get. If not specified, it returns the latest, released version. If you don’t have a released version, you must specify a version; otherwise, the list is empty.

Response Body

Field	Type	Description
data	Object[]	A list that contains the specified extension.
author_name	String	The name of the user or organization that owns the extension.
bits_enabled	Boolean	A Boolean value that determines whether the extension has features that use Bits. Is true if the extension has features that use Bits.
can_install	Boolean	A Boolean value that determines whether a user can install the extension on their channel. Is true if a user can install the extension. Typically, this is set to false if the extension is currently in testing mode and requires users to be allowlisted (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Access).
configuration_location	String	The location of where the extension’s configuration is stored. Possible values are: hosted — The Extensions Configuration Service hosts the configuration. custom — The Extension Backend Service (EBS) hosts the configuration. none — The extension doesn't require configuration.
description	String	A longer description of the extension. It appears on the details page.
eula_tos_url	String	A URL to the extension’s Terms of Service.
has_chat_support	Boolean	A Boolean value that determines whether the extension can communicate with the installed channel’s chat. Is true if the extension can communicate with the channel’s chat room.
icon_url	String	A URL to the default icon that’s displayed in the Extensions directory.
icon_urls	map[string]string	A dictionary that contains URLs to different sizes of the default icon. The dictionary’s key identifies the icon’s size (for example, 24x24), and the dictionary’s value contains the URL to the icon.
id	String	The extension’s ID.
name	String	The extension’s name.
privacy_policy_url	String	A URL to the extension’s privacy policy.
request_identity_link	Boolean	A Boolean value that determines whether the extension wants to explicitly ask viewers to link their Twitch identity.
screenshot_urls	String[]	A list of URLs to screenshots that are shown in the Extensions marketplace.
state	String	The extension’s state. Possible values are: Approved AssetsUploaded Deleted Deprecated InReview InTest PendingAction Rejected Released
subscriptions_support_level	String	Indicates whether the extension can view the user’s subscription level on the channel that the extension is installed on. Possible values are: none — The extension can't view the user’s subscription level. optional — The extension can view the user’s subscription level.
summary	String	A short description of the extension that streamers see when hovering over the discovery splash screen in the Extensions manager.
support_email	String	The email address that users use to get support for the extension.
version	String	The extension’s version number.
viewer_summary	String	A brief description displayed on the channel to explain how the extension works.
views	Object	Describes all views-related information such as how the extension is displayed on mobile devices.
mobile	Object	Describes how the extension is displayed on mobile devices.
viewer_url	String	The HTML file that is shown to viewers on mobile devices. This page is presented to viewers as a panel behind the chat area of the mobile app.
panel	Object	Describes how the extension is rendered if the extension may be activated as a panel extension.
viewer_url	String	The HTML file that is shown to viewers on the channel page when the extension is activated in a Panel slot.
height	Integer	The height, in pixels, of the panel component that the extension is rendered in.
can_link_external_content	Boolean	A Boolean value that determines whether the extension can link to non-Twitch domains.
video_overlay	Object	Describes how the extension is rendered if the extension may be activated as a video-overlay extension.
viewer_url	String	The HTML file that is shown to viewers on the channel page when the extension is activated on the Video - Overlay slot.
can_link_external_content	Boolean	A Boolean value that determines whether the extension can link to non-Twitch domains.
component	Object	Describes how the extension is rendered if the extension may be activated as a video-component extension.
viewer_url	String	The HTML file that is shown to viewers on the channel page when the extension is activated in a Video - Component slot.
aspect_ratio_x	Integer	The width value of the ratio (width : height) which determines the extension’s width, and how the extension’s iframe will resize in different video player environments.
aspect_ratio_y	Integer	The height value of the ratio (width : height) which determines the extension’s height, and how the extension’s iframe will resize in different video player environments.
autoscale	Boolean	A Boolean value that determines whether to apply CSS zoom. If true, a CSS zoom is applied such that the size of the extension is variable but the inner dimensions are fixed based on Scale Pixels. This allows your extension to render as if it is of fixed width and height. If false, the inner dimensions of the extension iframe are variable, meaning your extension must implement responsiveness.
scale_pixels	Integer	The base width, in pixels, of the extension to use when scaling (see `autoscale`). This value is ignored if `autoscale` is false.
target_height	Integer	The height as a percent of the maximum height of a video component extension. Values are between 1% - 100%.
can_link_external_content	Boolean	A Boolean value that determines whether the extension can link to non-Twitch domains.
config	Object	Describes the view that is shown to broadcasters while they are configuring your extension within the Extension Manager.
viewer_url	String	The HTML file shown to broadcasters while they are configuring your extension within the Extension Manager.
can_link_external_content	Boolean	A Boolean value that determines whether the extension can link to non-Twitch domains.
allowlisted_config_urls	String[]	Allowlisted configuration URLs for displaying the extension (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Capabilities).
allowlisted_panel_urls	String[]	Allowlisted panel URLs for displaying the extension (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Capabilities).

Response Codes

Code	Description
200 OK	Successfully retrieved the list of extensions.
400 Bad Request	The extension_id query parameter is required.
401 Unauthorized	The request must specify the Authorization header. The Authorization header is required and must specify a JWT token. The JWT token is not valid. The request must specify the Client-Id header.
404 Not Found	The extension in the extension_id query parameter was not found.

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. Returns the extension if its state is Released.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
extension_id	String	Yes	The ID of the extension to get.
extension_version	String	No	The version of the extension to get. If not specified, it returns the latest version.

Response Body

Field	Type	Description
data	Object[]	A list that contains the specified extension.
author_name	String	The name of the user or organization that owns the extension.
bits_enabled	Boolean	A Boolean value that determines whether the extension has features that use Bits. Is true if the extension has features that use Bits.
can_install	Boolean	A Boolean value that determines whether a user can install the extension on their channel. Is true if a user can install the extension. Typically, this is set to false if the extension is currently in testing mode and requires users to be allowlisted (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Access).
configuration_location	String	The location of where the extension’s configuration is stored. Possible values are: hosted — The Extensions Configuration Service hosts the configuration. custom — The Extension Backend Service (EBS) hosts the configuration. none — The extension doesn't require configuration.
description	String	A longer description of the extension. It appears on the details page.
eula_tos_url	String	A URL to the extension’s Terms of Service.
has_chat_support	Boolean	A Boolean value that determines whether the extension can communicate with the installed channel’s chat. Is true if the extension can communicate with the channel’s chat room.
icon_url	String	A URL to the default icon that’s displayed in the Extensions directory.
icon_urls	map[string]string	A dictionary that contains URLs to different sizes of the default icon. The dictionary’s key identifies the icon’s size (for example, 24x24), and the dictionary’s value contains the URL to the icon.
id	String	The extension’s ID.
name	String	The extension’s name.
privacy_policy_url	String	A URL to the extension’s privacy policy.
request_identity_link	Boolean	A Boolean value that determines whether the extension wants to explicitly ask viewers to link their Twitch identity.
screenshot_urls	String[]	A list of URLs to screenshots that are shown in the Extensions marketplace.
state	String	The extension’s state. Possible values are: Approved AssetsUploaded Deleted Deprecated InReview InTest PendingAction Rejected Released
subscriptions_support_level	String	Indicates whether the extension can view the user’s subscription level on the channel that the extension is installed on. Possible values are: none — The extension can't view the user’s subscription level. optional — The extension can view the user’s subscription level.
summary	String	A short description of the extension that streamers see when hovering over the discovery splash screen in the Extensions manager.
support_email	String	The email address that users use to get support for the extension.
version	String	The extension’s version number.
viewer_summary	String	A brief description displayed on the channel to explain how the extension works.
views	Object	Describes all views-related information such as how the extension is displayed on mobile devices.
mobile	Object	Describes how the extension is displayed on mobile devices.
viewer_url	String	The HTML file that is shown to viewers on mobile devices. This page is presented to viewers as a panel behind the chat area of the mobile app.
panel	Object	Describes how the extension is rendered if the extension may be activated as a panel extension.
viewer_url	String	The HTML file that is shown to viewers on the channel page when the extension is activated in a Panel slot.
height	Integer	The height, in pixels, of the panel component that the extension is rendered in.
can_link_external_content	Boolean	A Boolean value that determines whether the extension can link to non-Twitch domains.
video_overlay	Object	Describes how the extension is rendered if the extension may be activated as a video-overlay extension.
viewer_url	String	The HTML file that is shown to viewers on the channel page when the extension is activated on the Video - Overlay slot.
can_link_external_content	Boolean	A Boolean value that determines whether the extension can link to non-Twitch domains.
component	Object	Describes how the extension is rendered if the extension may be activated as a video-component extension.
viewer_url	String	The HTML file that is shown to viewers on the channel page when the extension is activated in a Video - Component slot.
aspect_ratio_x	Integer	The width value of the ratio (width : height) which determines the extension’s width, and how the extension’s iframe will resize in different video player environments.
aspect_ratio_y	Integer	The height value of the ratio (width : height) which determines the extension’s height, and how the extension’s iframe will resize in different video player environments.
autoscale	Boolean	A Boolean value that determines whether to apply CSS zoom. If true, a CSS zoom is applied such that the size of the extension is variable but the inner dimensions are fixed based on Scale Pixels. This allows your extension to render as if it is of fixed width and height. If false, the inner dimensions of the extension iframe are variable, meaning your extension must implement responsiveness.
scale_pixels	Integer	The base width, in pixels, of the extension to use when scaling (see `autoscale`). This value is ignored if `autoscale` is false.
target_height	Integer	The height as a percent of the maximum height of a video component extension. Values are between 1% - 100%.
can_link_external_content	Boolean	A Boolean value that determines whether the extension can link to non-Twitch domains.
config	Object	Describes the view that is shown to broadcasters while they are configuring your extension within the Extension Manager.
viewer_url	String	The HTML file shown to broadcasters while they are configuring your extension within the Extension Manager.
can_link_external_content	Boolean	A Boolean value that determines whether the extension can link to non-Twitch domains.
allowlisted_config_urls	String[]	Allowlisted configuration URLs for displaying the extension (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Capabilities).
allowlisted_panel_urls	String[]	Allowlisted panel URLs for displaying the extension (the allowlist is configured on Twitch’s developer site under the Extensions -> Extension -> Version -> Capabilities).

Response Codes

Code	Description
200 OK	Successfully retrieved the extension.
400 Bad Request	The extension_id query parameter is required.
401 Unauthorized	The Authorization header must specify an app access token or user access token. The access token is not valid. The ID in the Client-Id header must match the client ID in the access token.
404 Not Found	The extension specified in the extension_id query parameter was not found or is not released.

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 the list of Bits products that belongs to the extension. The client ID in the app access token identifies the extension.

Authorization

Requires an app access token. The client ID in the app access token must be the extension’s client ID.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
should_include_all	Boolean	No	A Boolean value that determines whether to include disabled or expired Bits products in the response. The default is false.

Response Body

Field	Type	Description
data	Object[]	A list of Bits products that the extension created. The list is in ascending SKU order. The list is empty if the extension hasn’t created any products or they’re all expired or disabled.
sku	String	The product’s SKU. The SKU is unique across an extension’s products.
cost	Object	An object that contains the product’s cost information.
amount	Integer	The product’s price.
type	String	The type of currency. Possible values are: bits
in_development	Boolean	A Boolean value that indicates whether the product is in development. If true, the product is not available for public use.
display_name	String	The product’s name as displayed in the extension.
expiration	String	The date and time, in RFC3339 format, when the product expires.
is_broadcast	Boolean	A Boolean value that determines whether Bits product purchase events are broadcast to all instances of an extension on a channel. The events are broadcast via the `onTransactionComplete` helper callback. Is true if the event is broadcast to all instances.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of products.
400 Bad Request	The ID in the Client-Id header must belong to an extension.
401 Unauthorized	The Authorization header is required and must specify an app access token; you may not specify a user access token. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.

Example Request

Gets the extension’s products including its disabled and expired products.

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

✎

Adds or updates a Bits product that the extension created. If the SKU doesn’t exist, the product is added. You may update all fields except the sku field.

Authorization

Requires an app access token. The client ID in the app access token must match the extension’s client ID.

URL

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

Request Body Parameters

Parameter	Type	Required?	Description
sku	String	Yes	The product's SKU. The SKU must be unique within an extension. The product's SKU cannot be changed. The SKU may contain only alphanumeric characters, dashes (-), underscores (_), and periods (.) and is limited to a maximum of 255 characters. No spaces.
cost	Object	Yes	An object that contains the product's cost information.
amount	Integer	Yes	The product's price.
type	String	Yes	The type of currency. Possible values are: bits — The minimum price is 1 and the maximum is 10000.
display_name	String	Yes	The product's name as displayed in the extension. The maximum length is 255 characters.
in_development	Boolean	No	A Boolean value that indicates whether the product is in development. Set to true if the product is in development and not available for public use. The default is false.
expiration	String	No	The date and time, in RFC3339 format, when the product expires. If not set, the product does not expire. To disable the product, set the expiration date to a date in the past.
is_broadcast	Boolean	No	A Boolean value that determines whether Bits product purchase events are broadcast to all instances of the extension on a channel. The events are broadcast via the `onTransactionComplete` helper callback. The default is false.

Response Body

Field	Type	Description
data	Object[]	A list of Bits products that the extension created. The list is in ascending SKU order. The list is empty if the extension hasn't created any products or they're all expired or disabled.
sku	String	The product's SKU. The SKU is unique across an extension's products.
cost	Object	An object that contains the product's cost information.
amount	Integer	The product's price.
type	String	The type of currency. Possible values are: bits
in_development	Boolean	A Boolean value that indicates whether the product is in development. If true, the product is not available for public use.
display_name	String	The product's name as displayed in the extension.
expiration	String	The date and time, in RFC3339 format, when the product expires.
is_broadcast	Boolean	A Boolean value that determines whether Bits product purchase events are broadcast to all instances of an extension on a channel. The events are broadcast via the `onTransactionComplete` helper callback. Is true if the event is broadcast to all instances.

Response Codes

Code	Description
200 OK	Successfully created the product.
400 Bad Request	The `sku` field is required. The value in the `sku` field is not valid. The SKU may contain only alphanumeric characters, dashes (-), underscores (_), and periods (.). The `cost` object's `amount` field is required. The value in the `cost` object's `amount` field is not valid. The <cost>cost</cost> object's `type` field is required. The value in the `cost` object's `type` field is not valid. The `display_name` field is required. The ID in the Client-Id header must belong to the extension.
401 Unauthorized	The Authorization header is required and must specify an app access token; you may not specify a user access token. The OAuth token is not valid. The ID in the Client-Id header must match the Client ID in the OAuth token.

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.

Authorization

If you use webhooks to receive events, the request must specify an app access token. The request will fail if you use a user access token. If the subscription type requires user authorization, the user must have granted your app (client ID) permissions to receive those events before you subscribe to them. For example, to subscribe to channel.subscribe events, your app must get a user access token that includes the channel:read:subscriptions scope, which adds the required permission to your app access token’s client ID.

If you use WebSockets to receive events, the request must specify a user access token. The request will fail if you use an app access token. If the subscription type requires user authorization, the token must include the required scope. However, if the subscription type doesn’t include user authorization, the token may include any scopes or no scopes.

If you use Conduits to receive events, the request must specify an app access token. The request will fail if you use a user access token.

URL

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

Request Body

Parameter	Type	Required	Description
type	String	Yes	The type of subscription to create. For a list of subscriptions that you can create, see Subscription Types. Set this field to the value in the Name column of the Subscription Types table.
version	String	Yes	The version number that identifies the definition of the subscription type that you want the response to use.
condition	Object	Yes	A JSON object that contains the parameter values that are specific to the specified subscription type. For the object’s required and optional fields, see the subscription type’s documentation.
transport	Object	Yes	The transport details that you want Twitch to use when sending you notifications.
method	String	Yes	The transport method. Possible values are: webhook websocket conduit
callback	String	No	The callback URL where the notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an event. Specify this field only if `method` is set to webhook. NOTE: Redirects are not followed.
secret	String	No	The secret used to verify the signature. The secret must be an ASCII string that’s a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message. Specify this field only if `method` is set to webhook.
session_id	String	No	An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message. Specify this field only if `method` is set to websocket.
conduit_id	String	No	An ID that identifies the conduit to send notifications to. When you create a conduit, the server returns the conduit ID. Specify this field only if `method` is set to conduit.

Response Body

Parameter	Type	Description
data	Object[]	A list that contains the single subscription that you created.
id	String	An ID that identifies the subscription.
status	String	The subscription’s status. The subscriber receives events only for enabled subscriptions. Possible values are: enabled — The subscription is enabled. webhook_callback_verification_pending — The subscription is pending verification of the specified callback URL (see Responding to a challenge request).
type	String	The subscription’s type. See Subscription Types.
version	String	The version number that identifies this definition of the subscription’s data.
condition	Object	The subscription’s parameter values. This is a string-encoded JSON object whose contents are determined by the subscription type.
created_at	String	The date and time (in RFC3339 format) of when the subscription was created.
transport	Object	The transport details used to send the notifications.
method	String	The transport method. Possible values are: webhook websocket conduit
callback	String	The callback URL where the notifications are sent. Included only if `method` is set to webhook.
session_id	String	An ID that identifies the WebSocket that notifications are sent to. Included only if `method` is set to websocket.
connected_at	String	The UTC date and time that the WebSocket connection was established. Included only if `method` is set to websocket.
conduit_id	String	An ID that identifies the conduit to send notifications to. Included only if `method` is set to conduit.
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.

Response Codes

Code	Meaning
202 Accepted	Successfully accepted the subscription request.
400 Bad Request	The `condition` field is required. The user specified in the `condition` object does not exist. The `condition` object is missing one or more required fields. The combination of values in the `version` and `type` fields is not valid. The length of the string in the `secret` field is not valid. The URL in the transport's `callback` field is not valid. The URL must use the HTTPS protocol and the 443 port number. The value specified in the `method` field is not valid. The `callback` field is required if you specify the webhook transport method. The `session_id` field is required if you specify the WebSocket transport method. The combination of subscription type and version is not valid. The `conduit_id` field is required if you specify the Conduit transport method.
401 Unauthorized	The Authorization header is required and must specify an app access token if the transport method is webhook. The Authorization header is required and must specify a user access token if the transport method is WebSocket. The access token is not valid. The ID in the Client-Id header must match the client ID in the access token.
403 Forbidden	The access token is missing the required scopes.
409 Conflict	A subscription already exists for the specified event type and `condition` combination.
429 Too Many Requests	The request exceeds the number of subscriptions that you may create with the same combination of `type` and `condition` values.

Example Request 1

For a webhook method type. 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 - Webhook

Example Response 1

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

Example Request 2

For a websocket method type.

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": "websocket",
        "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
    }
}'

Example Response 2

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

Example Request 3

For a conduit method type.

Example RequestExample Requestcurl -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":"conduit",
        "conduit_id":"bfcfc993-26b1-b876-44d9-afe75a379dac"
    }
}'

Example Response 3

{
  "data": [
    {
      "id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
      "status": "enabled",
      "type": "user.update",
      "version": "1",
      "condition": {
        "user_id": "1234"
      },
      "created_at": "2020-11-10T14:32:18.730260295Z",
      "transport": {
        "method": "conduit",
        "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
      },
      "cost": 1
    }
  ],
  "total": 1,
  "total_cost": 1,
  "max_total_cost": 10000
}

Delete EventSub Subscription

✎

Deletes an EventSub subscription.

Authorization

If you use webhooks to receive events, the request must specify an app access token. The request will fail if you use a user access token.

If you use WebSockets to receive events, the request must specify a user access token. The request will fail if you use an app access token. The token may include any scopes.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
id	String	Yes	The ID of the subscription to delete.

Response Codes

Code	Description
204 No Content	Successfully deleted the subscription.
400 Bad Request	The id query parameter is required.
401 Unauthorized	The Authorization header is required and must specify an app access token. The access token is not valid. The ID in the Client-Id header must match the client ID in the access token.
404 Not Found	The subscription was not found.

Example Request

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

Get EventSub Subscriptions

✎

Gets a list of EventSub subscriptions that the client in the access token created.

Authorization

If you use Webhooks or Conduits to receive events, the request must specify an app access token. The request will fail if you use a user access token.

If you use WebSockets to receive events, the request must specify a user access token. The request will fail if you use an app access token. The token may include any scopes.

URL

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

Request 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	Required?	Description
status	String	No	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. moderator_removed — The moderator that authorized the subscription is no longer one of the broadcaster's moderators. user_removed — One of the users specified in the Condition object was removed. chat_user_banned - The user specified in the Condition object was banned from the broadcaster's chat. version_removed — The subscription to subscription type and version is no longer supported. beta_maintenance — The subscription to the beta subscription type was removed due to maintenance. websocket_disconnected — The client closed the connection. websocket_failed_ping_pong — The client failed to respond to a ping message. websocket_received_inbound_traffic — The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message). websocket_connection_unused — The client failed to subscribe to events within the required time. websocket_internal_error — The Twitch WebSocket server experienced an unexpected error. websocket_network_timeout — The Twitch WebSocket server timed out writing the message to the client. websocket_network_error — The Twitch WebSocket server experienced a network error writing the message to the client. websocket_failed_to_reconnect - The client failed to reconnect to the Twitch WebSocket server within the required time after a Reconnect Message.
type	String	No	Filter subscriptions by subscription type. For a list of subscription types, see Subscription Types.
user_id	String	No	Filter subscriptions by user ID. The response contains subscriptions where this ID matches a user ID that you specified in the Condition object when you created the subscription.
after	String	No	The cursor used to get the next page of results. The `pagination` object in the response contains the cursor's value.

Response Body

Field	Type	Description
data	Object[]	The list of subscriptions. The list is ordered by the oldest subscription first. The list is empty if the client hasn't created subscriptions or there are no subscriptions that match the specified filter criteria.
id	String	An ID that identifies the subscription.
status	String	The subscription's status. The subscriber receives events only for enabled subscriptions. 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. moderator_removed — The moderator that authorized the subscription is no longer one of the broadcaster's moderators. user_removed — One of the users specified in the Condition object was removed. version_removed — The subscription to subscription type and version is no longer supported. beta_maintenance — The subscription to the beta subscription type was removed due to maintenance. websocket_disconnected — The client closed the connection. websocket_failed_ping_pong — The client failed to respond to a ping message. websocket_received_inbound_traffic — The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message). websocket_connection_unused — The client failed to subscribe to events within the required time. websocket_internal_error — The Twitch WebSocket server experienced an unexpected error. websocket_network_timeout — The Twitch WebSocket server timed out writing the message to the client. websocket_network_error — The Twitch WebSocket server experienced a network error writing the message to the client.
type	String	The subscription's type. See Subscription Types.
version	String	The version number that identifies this definition of the subscription's data.
condition	Object	The subscription's parameter values. This is a string-encoded JSON object whose contents are determined by the subscription type.
created_at	String	The date and time (in RFC3339 format) of when the subscription was created.
transport	Object	The transport details used to send the notifications.
method	String	The transport method. Possible values are: webhook websocket
callback	String	The callback URL where the notifications are sent. Included only if `method` is set to webhook.
session_id	String	An ID that identifies the WebSocket that notifications are sent to. Included only if `method` is set to websocket.
connected_at	String	The UTC date and time that the WebSocket connection was established. Included only if `method` is set to websocket.
disconnected_at	String	The UTC date and time that the WebSocket connection was lost. Included only if `method` is set to websocket.
cost	Integer	The amount that the subscription counts against your limit. Learn More
total	Integer	The total number of subscriptions that 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 that you create.
pagination	Object	An object that contains the cursor used to get the next page of subscriptions. The object is empty if 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	Description
200 OK	Successfully retrieved the subscriptions.
400 Bad Request	The request may specify only one filter query parameter. For example, either type or status or user_id. The value in the type query parameter is not valid. The value in the status query parameter is not valid. The cursor specified in the after query parameter is not valid.
401 Unauthorized	The Authorization header is required and must specify an app access token. The access token is not valid. The ID in the Client-Id header must match the client ID in the access token.

Example Request

Gets a list of EventSub subscriptions that you created. The list is 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 information about all broadcasts on Twitch.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/games/top

Request Query Parameters

Parameter	Type	Required ?	Description
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 items per page. 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
before	String	No	The cursor used to get the previous page of results. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Fields	Type	Description
data	Object[]	The list of broadcasts. The broadcasts are sorted by the number of viewers, with the most popular first.
id	String	An ID that identifies the category or game.
name	String	The category’s or game’s name.
box_art_url	String	A URL to the category’s or game’s box art. You must replace the `{width}x{height}` placeholder with the size of image you want.
igdb_id	String	The ID that IGDB uses to identify this game. If the IGDB ID is not available to Twitch, this field is set to an empty string.
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 or before query parameter to get the next or previous page of results.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of broadcasts.
400 Bad Request	The value in the first query parameter is not valid. The cursor in the after or before query parameter is not valid.
401 Unauthorized	The Authorization header is required and must specify an app access token or user access token. The access token is not valid. The ID in the Client-Id header must match the client ID in the access token.

Example Request

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

Example Response

{
  "data": [
    {
      "id": "493057",
      "name": "PUBG: BATTLEGROUNDS",
      "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/493057-{width}x{height}.jpg",
      "igdb_id": "27789"
    },
    ...
  ],
  "pagination":{"cursor":"eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6MjB9fQ=="}
}

Get Games

✎

Gets information about specified categories or games.

You may get up to 100 categories or games by specifying their ID or name. You may specify all IDs, all names, or a combination of IDs and names. If you specify a combination of IDs and names, the total number of IDs and names must not exceed 100.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
id	String	Yes	The ID of the category or game to get. Include this parameter for each category or game you want to get. For example, `&id=1234&id=5678`. You may specify a maximum of 100 IDs. The endpoint ignores duplicate and invalid IDs or IDs that weren’t found.
name	String	Yes	The name of the category or game to get. The name must exactly match the category’s or game’s title. Include this parameter for each category or game you want to get. For example, `&name=foo&name=bar`. You may specify a maximum of 100 names. The endpoint ignores duplicate names and names that weren’t found.
igdb_id	String	Yes	The IGDB ID of the game to get. Include this parameter for each game you want to get. For example, `&igdb_id=1234&igdb_id=5678`. You may specify a maximum of 100 IDs. The endpoint ignores duplicate and invalid IDs or IDs that weren’t found.

Response Body

Fields	Type	Description
data	Object[]	The list of categories and games. The list is empty if the specified categories and games weren’t found.
id	String	An ID that identifies the category or game.
name	String	The category’s or game’s name.
box_art_url	String	A URL to the category’s or game’s box art. You must replace the `{width}x{height}` placeholder with the size of image you want.
igdb_id	String	The ID that IGDB uses to identify this game. If the IGDB ID is not available to Twitch, this field is set to an empty string.

Response Codes

Code	Description
200 OK	Successfully retrieved the specified games.
400 Bad Request	The request must specify the id or name or igdb_id query parameter. The combined number of game IDs (id and igdb_id) and game names that you specify in the request must not exceed 100.
401 Unauthorized	The Authorization header is required and must specify an app access token or user access token. The access token is not valid. The ID in the Client-Id header must match the client ID in the access token.

Example Request

curl -X GET 'https://api.twitch.tv/helix/games?id=33214' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "33214",
      "name": "Fortnite",
      "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/33214-{width}x{height}.jpg",
      "igdb_id": "1905"
    }
  ]
}

Get Creator Goals

✎

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

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

Authorization

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

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that created the goals. This ID must match the user ID in the user access token.

Response Body

Field	Type	Description
data	Object[]	The list of goals. The list is empty if the broadcaster hasn’t created goals.
id	String	An ID that identifies this goal.
broadcaster_id	String	An ID that identifies the broadcaster that created the goal.
broadcaster_name	String	The broadcaster’s display name.
broadcaster_login	String	The broadcaster’s login name.
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. Is an empty string if not specified.
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 date and time (in RFC3339 format) that the broadcaster created the goal.

Response Codes

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

Example Request

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 the 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 Channel Guest Star Settings

✎

BETA Gets the channel settings for configuration of the Guest Star feature for a particular host.

Authorization

Query parameter moderator_id must match the user_id in the User-Access token
Requires OAuth Scope: channel:read:guest_star, channel:manage:guest_star, moderator:read:guest_star or moderator:manage:guest_star

URL

GET https://api.twitch.tv/helix/guest_star/channel_settings

Request Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster you want to get guest star settings for.
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 in the user access token.

Response Body

Parameter	Type	Description
is_moderator_send_live_enabled	Boolean	Flag determining if Guest Star moderators have access to control whether a guest is live once assigned to a slot.
slot_count	Integer	Number of slots the Guest Star call interface will allow the host to add to a call. Required to be between 1 and 6.
is_browser_source_audio_enabled	Boolean	Flag determining if Browser Sources subscribed to sessions on this channel should output audio
group_layout	String	This setting determines how the guests within a session should be laid out within the browser source. Can be one of the following values: `TILED_LAYOUT`: All live guests are tiled within the browser source with the same size. `SCREENSHARE_LAYOUT`: All live guests are tiled within the browser source with the same size. If there is an active screen share, it is sized larger than the other guests.
browser_source_token	String	View only token to generate browser source URLs

Response Codes

Code	Meaning
400 Bad Request	Missing broadcaster_id Missing moderator_id
403 Forbidden	Insufficient authorization for viewing channel’s Guest Star settings

Example Request

curl -x GET `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049&moderator_id=9321049` \

-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \

-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [        
    { 
      "is_moderator_send_live_enabled": true,            "slot_count": 4,            "is_browser_source_audio_enabled": true,            "layout": "TILED_LAYOUT",            "browser_source_token": "eihq8rew7q3hgierufhi3q"        
    }    
  ]
}

Update Channel Guest Star Settings

✎

BETA Mutates the channel settings for configuration of the Guest Star feature for a particular host.

Authorization

Query parameter broadcaster_id must match the user_id in the User-Access token
Requires OAuth Scope: channel:manage:guest_star

URL

PUT https://api.twitch.tv/helix/guest_star/channel_settings

Request Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster you want to update Guest Star settings for.

Request Body

Parameter	Required	Type	Description
is_moderator_send_live_enabled	No	Boolean	Flag determining if Guest Star moderators have access to control whether a guest is live once assigned to a slot.
slot_count	No	Integer	Number of slots the Guest Star call interface will allow the host to add to a call. Required to be between 1 and 6.
is_browser_source_audio_enabled	No	Boolean	Flag determining if Browser Sources subscribed to sessions on this channel should output audio
group_layout	No	String	This setting determines how the guests within a session should be laid out within the browser source. Can be one of the following values: `TILED_LAYOUT`: All live guests are tiled within the browser source with the same size. `SCREENSHARE_LAYOUT`: All live guests are tiled within the browser source with the same size. If there is an active screen share, it is sized larger than the other guests. `HORIZONTAL_LAYOUT`: All live guests are arranged in a horizontal bar within the browser source `VERTICAL_LAYOUT`: All live guests are arranged in a vertical bar within the browser source
regenerate_browser_sources	No	Boolean	Flag determining if Guest Star should regenerate the auth token associated with the channel’s browser sources. Providing a true value for this will immediately invalidate all browser sources previously configured in your streaming software.

Response Codes

Code	Meaning
204 No Content	Successfully updated channel settings
400 Bad Request	Missing broadcaster_id Invalid slot_count Invalid group_layout

Example Request 1

Update browser source layout settings

curl -x PUT `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049&group_layout=TILED_LAYOUT` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Request 2

Disable moderator control of slot live setting

curl -x PUT `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049&is_moderator_send_live_enabled=false` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Request 3

Update max slot count

curl -x PUT `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049&slot_count=6` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Request 4

Regenerate browser sources

curl -x PUT `https://api.twitch.tv/helix/guest_star/channel_settings?broadcaster_id=9321049&regenerate_browser_sources=true` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Get Guest Star Session

✎

BETA Gets information about an ongoing Guest Star session for a particular channel.

Authorization

Requires OAuth Scope: channel:read:guest_star, channel:manage:guest_star, moderator:read:guest_star or moderator:manage:guest_star
Guests must be either invited or assigned a slot within the session

URL

GET https://api.twitch.tv/helix/guest_star/session

Request Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	ID for the user hosting the Guest Star session.
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 in the user access token.

Response Body

Parameter	Type	Description
data	Session[]	Summary of the session details
id	String	ID uniquely representing the Guest Star session.
guests	Guest	List of guests currently interacting with the Guest Star session.
slot_id	String	ID representing this guest’s slot assignment. Host is always in slot "0" Guests are assigned the following consecutive IDs (e.g, "1", "2", "3", etc) Screen Share is represented as a special guest with the ID "SCREENSHARE" The identifier here matches the ID referenced in browser source links used in broadcasting software.
is_live	Boolean	Flag determining whether or not the guest is visible in the browser source in the host’s streaming software.
user_id	String	User ID of the guest assigned to this slot.
user_display_name	String	Display name of the guest assigned to this slot.
user_login	String	Login of the guest assigned to this slot.
volume	Integer	Value from 0 to 100 representing the host’s volume setting for this guest.
assigned_at	String	Timestamp when this guest was assigned a slot in the session.
audio_settings	MediaSettings	Information about the guest’s audio settings
is_host_enabled	Boolean	Flag determining whether the host is allowing the guest’s audio to be seen or heard within the session.
is_guest_enabled	Boolean	Flag determining whether the guest is allowing their audio to be transmitted to the session.
is_available	Boolean	Flag determining whether the guest has an appropriate audio device available to be transmitted to the session.
video_settings	MediaSettings	Information about the guest’s video settings
is_host_enabled	Boolean	Flag determining whether the host is allowing the guest’s video to be seen or heard within the session.
is_guest_enabled	Boolean	Flag determining whether the guest is allowing their video to be transmitted to the session.
is_available	Boolean	Flag determining whether the guest has an appropriate video device available to be transmitted to the session.

Response Codes

Code	Meaning
400 Bad Request	Missing broadcaster_id Missing moderator_id
401 Unauthenticated	moderator_id and user token do not match

Example Request

Get session for host channel

curl -x GET `https://api.twitch.tv/helix/guest_star/session?broadcaster_id=9321049&moderator_id=9321049` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
    "data": [
        {
            "id": "2KFRQbFtpmfyD3IevNRnCzOPRJI",
            "guests": [
                {
                    "slot_id": "0",
                    "user_id": "9321049",
                    "user_display_name": "Cool_User",
                    "user_login": "cool_user",
                    "is_live": true,
                    "volume": 100,
                    "assigned_at": "2023-01-02T04:16:53.325Z",
                    "audio_settings": {
                        "is_available": true,
                        "is_host_enabled": true,
                        "is_guest_enabled": true,
                    },
                    "video_settings": {
                        "is_available": true,
                        "is_host_enabled": true,
                        "is_guest_enabled": true,
                    }
                },
                {
                    "slot_id": "1",
                    "user_id": "144601104",
                    "user_display_name": "Cool_Guest",
                    "user_login": "cool_guest",
                    "is_live": true,
                    "volume": 100,
                    "assigned_at": "2023-01-02T04:20:59.325Z",
                    "audio_settings": {
                        "is_available": true,
                        "is_host_enabled": true,
                        "is_guest_enabled": true,
                    },
                    "video_settings": {
                        "is_available": true,
                        "is_host_enabled": true,
                        "is_guest_enabled": true,
                    }
                }
            ]
        }
    ]
}

Create Guest Star Session

✎

BETA Programmatically creates a Guest Star session on behalf of the broadcaster. Requires the broadcaster to be present in the call interface, or the call will be ended automatically.

Authorization

Query parameter broadcaster_id must match the user_id in the User-Access token
Requires OAuth Scope: channel:manage:guest_star

URL

POST https://api.twitch.tv/helix/guest_star/session

Request Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster you want to create a Guest Star session for. Provided `broadcaster_id` must match the `user_id` in the auth token.

Response Body

Parameter	Type	Description
data	Session[]	Summary of the session details.
id	String	ID uniquely representing the Guest Star session.
guests	Guest	List of guests currently interacting with the Guest Star session. On creation, the session will contain the broadcaster as a solo guest.
slot_id	String	ID representing this guest’s slot assignment. Host is always in slot "0" Guests are assigned the following consecutive IDs (e.g, "1", "2", "3", etc) Screen Share is represented as a special guest with the ID "SCREENSHARE" The identifier here matches the ID referenced in browser source links used in broadcasting software.
is_live	Boolean	Flag determining whether or not the guest is visible in the browser source in the host’s streaming software.
user_id	String	User ID of the guest assigned to this slot.
user_display_name	String	Display name of the guest assigned to this slot.
user_login	String	Login of the guest assigned to this slot.
volume	Integer	Value from 0 to 100 representing the host’s volume setting for this guest.
assigned_at	String	Timestamp when this guest was assigned a slot in the session.
audio_settings	MediaSettings	Information about the guest’s audio settings
is_host_enabled	Boolean	Flag determining whether the host is allowing the guest’s audio to be seen or heard within the session.
is_guest_enabled	Boolean	Flag determining whether the guest is allowing their audio to be transmitted to the session.
is_available	Boolean	Flag determining whether the guest has an appropriate audio device available to be transmitted to the session.
video_settings	MediaSettings	Information about the guest’s video settings
is_host_enabled	Boolean	Flag determining whether the host is allowing the guest’s video to be seen or heard within the session.
is_guest_enabled	Boolean	Flag determining whether the guest is allowing their video to be transmitted to the session.
is_available	Boolean	Flag determining whether the guest has an appropriate video device available to be transmitted to the session.

Response Codes

Code	Meaning
400 Bad Request	Missing broadcaster_id Session limit reached (1 active call)
401 Unauthorized	Phone verification missing
403 Forbidden	Insufficient authorization for creating session

Example Request

Start Guest Star session

curl -x POST `https://api.twitch.tv/helix/guest_star/session?broadcaster_id=9321049` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
    "data": [
        {
            "id": "2KFRQbFtpmfyD3IevNRnCzOPRJI",
            "guests": [
                {
                    "id": "0",
                    "user_id": "9321049",
                    "user_display_name": "Cool_User",
                    "user_login": "cool_user",
                    "is_live": true,
                    "volume": 100,
                    "assigned_at": "2023-01-02T04:16:53.325Z",
                    "audio_settings": {
                        "is_available": true,
                        "is_host_enabled": true,
                        "is_guest_enabled": true,
                    },
                    "video_settings": {
                        "is_available": true,
                        "is_host_enabled": true,
                        "is_guest_enabled": true,
                    }
                },
            ]
        },
    ]
}

End Guest Star Session

✎

BETA Programmatically ends a Guest Star session on behalf of the broadcaster. Performs the same action as if the host clicked the “End Call” button in the Guest Star UI.

Authorization

Query parameter broadcaster_id must match the user_id in the User-Access token
Requires OAuth Scope: channel:manage:guest_star

URL

DELETE https://api.twitch.tv/helix/guest_star/session

Request Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster you want to end a Guest Star session for. Provided `broadcaster_id` must match the `user_id` in the auth token.
session_id	Yes	String	ID for the session to end on behalf of the broadcaster.

Response Body

Parameter	Type	Description
data	Session[]	Summary of the session details when the session was ended.
id	String	ID uniquely representing the Guest Star session.
guests	Guest	List of guests currently interacting with the Guest Star session.
slot_id	String	ID representing this guest’s slot assignment. Host is always in slot "0" Guests are assigned the following consecutive IDs (e.g, "1", "2", "3", etc) Screen Share is represented as a special guest with the ID "SCREENSHARE" The identifier here matches the ID referenced in browser source links used in broadcasting software.
is_live	Boolean	Flag determining whether or not the guest is visible in the browser source in the host’s streaming software.
user_id	String	User ID of the guest assigned to this slot.
user_display_name	String	Display name of the guest assigned to this slot.
user_login	String	Login of the guest assigned to this slot.
volume	Integer	Value from 0 to 100 representing the host’s volume setting for this guest.
assigned_at	String	Timestamp when this guest was assigned a slot in the session.
audio_settings	MediaSettings	Information about the guest’s audio settings
is_host_enabled	Boolean	Flag determining whether the host is allowing the guest’s audio to be seen or heard within the session.
is_guest_enabled	Boolean	Flag determining whether the guest is allowing their audio to be transmitted to the session.
is_available	Boolean	Flag determining whether the guest has an appropriate audio device available to be transmitted to the session.
video_settings	MediaSettings	Information about the guest’s video settings
is_host_enabled	Boolean	Flag determining whether the host is allowing the guest’s video to be seen or heard within the session.
is_guest_enabled	Boolean	Flag determining whether the guest is allowing their video to be transmitted to the session.
is_available	Boolean	Flag determining whether the guest has an appropriate video device available to be transmitted to the session.

Response Codes

Code	Meaning
400 Bad Request	Missing or invalid broadcaster_id Missing or invalid session_id Session has already been ended
403 Forbidden	Insufficient authorization for ending session

Example Request

End Guest Star session

curl -x DELETE `https://api.twitch.tv/helix/guest_star/session?broadcaster_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
    "data": [
        {
            "id": "2KFRQbFtpmfyD3IevNRnCzOPRJI",
            "guests": [
                {
                    "id": "0",
                    "user_id": "9321049",
                    "user_display_name": "Cool_User",
                    "user_login": "cool_user",
                    "is_live": true,
                    "volume": 100,
                    "assigned_at": "2023-01-02T04:16:53.325Z",
                    "audio_settings": {
                        "is_available": true,
                        "is_host_enabled": true,
                        "is_guest_enabled": true,
                    },
                    "video_settings": {
                        "is_available": true,
                        "is_host_enabled": true,
                        "is_guest_enabled": true,
                    }
                },
            ]
        }
    ]
}

Get Guest Star Invites

✎

BETA Provides the caller with a list of pending invites to a Guest Star session, including the invitee’s ready status while joining the waiting room.

Authorization

Query parameter broadcaster_id must match the user_id in the User-Access token
Requires OAuth Scope: channel:read:guest_star, channel:manage:guest_star, moderator:read:guest_star or moderator:manage:guest_star

URL

GET https://api.twitch.tv/helix/guest_star/invites

Request Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster running the Guest Star session.
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` in the user access token.
session_id	Yes	String	The session ID to query for invite status.

Response Body

Parameter	Type	Description
data	Invite[]	A list of invite objects describing the invited user as well as their ready status.
user_id	String	Twitch User ID corresponding to the invited guest
invited_at	string	Timestamp when this user was invited to the session.
status	string	Status representing the invited user’s join state. Can be one of the following: `INVITED`: The user has been invited to the session but has not acknowledged it. `ACCEPTED`: The invited user has acknowledged the invite and joined the waiting room, but may still be setting up their media devices or otherwise preparing to join the call. `READY`: The invited user has signaled they are ready to join the call from the waiting room.
is_video_enabled	Boolean	Flag signaling that the invited user has chosen to disable their local video device. The user has hidden themselves, but they may choose to reveal their video feed upon joining the session.
is_audio_enabled	Boolean	Flag signaling that the invited user has chosen to disable their local audio device. The user has muted themselves, but they may choose to unmute their audio feed upon joining the session.
is_video_available	Boolean	Flag signaling that the invited user has a video device available for sharing.
is_audio_available	Boolean	Flag signaling that the invited user has an audio device available for sharing.

Response Codes

Code	Meaning
400 Bad Request	Missing broadcaster_id Missing session_id

Example Request 1

Get session invites

curl -x GET `https://api.twitch.tv/helix/guest_star/invites?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Request 2

Get session for host channel

curl -x GET `https://api.twitch.tv/helix/guest_star/session?broadcaster_id=9321049` \ -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \ -H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response 2

{
  "data": [
    {
      "user_id": "144601104",
      "invited_at": "2023-01-02T04:16:53.325Z",
      "status": "INVITED",
      "is_audio_enabled": false,
      "is_video_enabled": true,
      "is_audio_available": true,
      "is_video_available": true
    }
  ]
}

Send Guest Star Invite

✎

BETA Sends an invite to a specified guest on behalf of the broadcaster for a Guest Star session in progress.

Authorization

Query parameter moderator_id must match the user_id in the User-Access token
Requires OAuth Scope: channel:manage:guest_star or moderator:manage:guest_star

URL

POST https://api.twitch.tv/helix/guest_star/invites

Request Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster running the Guest Star session.
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` in the user access token.
session_id	Yes	String	The session ID for the invite to be sent on behalf of the broadcaster.
guest_id	Yes	String	Twitch User ID for the guest to invite to the Guest Star session.

Response Codes

Code	Meaning
400 Bad Request	Missing broadcaster_id Missing moderator_id Missing session_id Missing guest_id Invalid session_id
403 Forbidden	Unauthorized guest invited Guest already invited

Example Request

Invite user to Guest Star session

curl -x POST `https://api.twitch.tv/helix/guest_star/invites?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&guest_id=144601104` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Delete Guest Star Invite

✎

BETA Revokes a previously sent invite for a Guest Star session.

Authorization

Query parameter moderator_id must match the user_id in the User-Access token
Requires OAuth Scope: channel:manage:guest_star or moderator:manage:guest_star

URL

DELETE https://api.twitch.tv/helix/guest_star/invites

Request Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster running the Guest Star session.
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` in the user access token.
session_id	Yes	String	The ID of the session for the invite to be revoked on behalf of the broadcaster.
guest_id	Yes	String	Twitch User ID for the guest to revoke the Guest Star session invite from.

Response Codes

Code	Meaning
400 Bad Request	Missing broadcaster_id Missing session_id Missing guest_id Invalid session_id
404 Not Found	No invite exists for specified guest_id

Example Request

Remove invite to session

curl -x DELETE `https://api.twitch.tv/helix/guest_star/invites?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&guest_id=144601104` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Assign Guest Star Slot

✎

BETA Allows a previously invited user to be assigned a slot within the active Guest Star session, once that guest has indicated they are ready to join.

Authorization

Query parameter moderator_id must match the user_id in the User-Access token
Requires OAuth Scope: channel:manage:guest_star or moderator:manage:guest_star

URL

POST https://api.twitch.tv/helix/guest_star/slot

Request Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster running the Guest Star session.
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` in the user access token.
session_id	Yes	String	The ID of the Guest Star session in which to assign the slot.
guest_id	Yes	String	The Twitch User ID corresponding to the guest to assign a slot in the session. This user must already have an invite to this session, and have indicated that they are ready to join.
slot_id	Yes	String	The slot assignment to give to the user. Must be a numeric identifier between “1” and “N” where N is the max number of slots for the session. Max number of slots allowed for the session is reported by Get Channel Guest Star Settings.

Response Codes

Code	Meaning
204 No Content	Successfuly assigned guest to slot
400 Bad Request	Missing broadcaster_id Missing moderator_id Missing guest_id Missing or invalid session_id Missing or invalid slot_id
401 Unauthorized	moderator_id is not a guest star moderator
403 Forbidden	Cannot assign host slot Guest not invited to session Guest already assigned to slot Guest is not ready to join

Example Request

Assign invited user to slot

curl -x POST `https://api.twitch.tv/helix/guest_star/slot?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&guest_id=144601104&slot_id=1` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
    "data": {
        "code": "USER_NOT_READY"
    }
}

Update Guest Star Slot

✎

BETA Allows a user to update the assigned slot for a particular user within the active Guest Star session.

Authorization

Query parameter moderator_id must match the user_id in the User-Access token
Requires OAuth Scope: channel:manage:guest_star or moderator:manage:guest_star

URL

PATCH https://api.twitch.tv/helix/guest_star/slot

Request Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster running the Guest Star session.
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` in the user access token.
session_id	Yes	String	The ID of the Guest Star session in which to update slot settings.
source_slot_id	Yes	String	The slot assignment previously assigned to a user.
destination_slot_id	No	String	The slot to move this user assignment to. If the destination slot is occupied, the user assigned will be swapped into `source_slot_id`.

Response Codes

Code	Meaning
204 No Content	Successfuly updated slot(s)
400 Bad Request	Missing broadcaster_id Missing or invalid session_id Missing or invalid slot_id

Example Request

Move slot assignment to a new slot ID

curl -x PATCH `https://api.twitch.tv/helix/guest_star/slot?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&source_slot_id=1&destination_slot_id=2` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Delete Guest Star Slot

✎

BETA Allows a caller to remove a slot assignment from a user participating in an active Guest Star session. This revokes their access to the session immediately and disables their access to publish or subscribe to media within the session.

Authorization

Query parameter moderator_id must match the user_id in the User-Access token
Requires OAuth Scope: channel:manage:guest_star or moderator:manage:guest_star

URL

DELETE https://api.twitch.tv/helix/guest_star/slot

Request Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster running the Guest Star session.
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 in the user access token.
session_id	Yes	String	The ID of the Guest Star session in which to remove the slot assignment.
guest_id	Yes	String	The Twitch User ID corresponding to the guest to remove from the session.
slot_id	Yes	String	The slot ID representing the slot assignment to remove from the session.
should_reinvite_guest	No	String	Flag signaling that the guest should be reinvited to the session, sending them back to the invite queue.

Response Codes

Code	Meaning
204 No Content	Successfuly removed user from slot
400 Bad Request	Missing broadcaster_id Missing moderator_id Missing or invalid session_id Missing or invalid slot_id
403 Forbidden	moderator_id is not a Guest Star moderator The request is attempting to modify a restricted slot
404 Not Found	guest_id or slot_id not found

Example Request

Remove user from slot

curl -x DELETE `https://api.twitch.tv/helix/guest_star/slot?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&guest_id=144601104&slot_id=1` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Update Guest Star Slot Settings

✎

BETA Allows a user to update slot settings for a particular guest within a Guest Star session, such as allowing the user to share audio or video within the call as a host. These settings will be broadcasted to all subscribers which control their view of the guest in that slot. One or more of the optional parameters to this API can be specified at any time.

Authorization

Query parameter moderator_id must match the user_id in the User-Access token
Requires OAuth Scope: channel:manage:guest_star or moderator:manage:guest_star

URL

PATCH https://api.twitch.tv/helix/guest_star/slot_settings

Request Query Parameters

Parameter	Required	Type	Description
broadcaster_id	Yes	String	The ID of the broadcaster running the Guest Star session.
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 in the user access token.
session_id	Yes	String	The ID of the Guest Star session in which to update a slot’s settings.
slot_id	Yes	String	The slot assignment that has previously been assigned to a user.
is_audio_enabled	No	Boolean	Flag indicating whether the slot is allowed to share their audio with the rest of the session. If false, the slot will be muted in any views containing the slot.
is_video_enabled	No	Boolean	Flag indicating whether the slot is allowed to share their video with the rest of the session. If false, the slot will have no video shared in any views containing the slot.
is_live	No	Boolean	Flag indicating whether the user assigned to this slot is visible/can be heard from any public subscriptions. Generally, this determines whether or not the slot is enabled in any broadcasting software integrations.
volume	No	Integer	Value from 0-100 that controls the audio volume for shared views containing the slot.

Response Codes

Code	Meaning
204 No Content	Successfuly updated slot settings
400 Bad Request	Missing broadcaster_id Missing moderator_id Missing or invalid session_id Missing or invalid slot_id
403 Forbidden	moderator_id is not a Guest Star moderator The request is attempting to modify a restricted slot

Example Request 1

Update slot settings to enable slot in broadcasting software

curl -x PATCH `https://api.twitch.tv/helix/guest_star/slot_settings?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&slot_id=1&is_audio_enabled=false` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Request 2

Mute a slot’s audio for a guest

curl -x PATCH `https://api.twitch.tv/helix/guest_star/slot_settings?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&slot_id=1&is_live=true` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Request 3

Allow slot audio to be unmuted by a guest. NOTE: This operation does not immediately unmute the guest. The guest will be notified they can unmute themselves when ready.

curl -x PATCH `https://api.twitch.tv/helix/guest_star/slot_settings?broadcaster_id=9321049&moderator_id=9321049&session_id=2KFRQbFtpmfyD3IevNRnCzOPRJI&slot_id=1&is_audio_enabled=true` \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Get Hype Train Events

✎

Gets information about the broadcaster’s current or most recent Hype Train event.

Instead of polling for events, consider subscribing to Hype Train events (Begin, Progress, End).

Authorization

Requires a user access token that includes the channel:read:hype_train scope.

URL

GET https://api.twitch.tv/helix/hypetrain/events

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that’s running the Hype Train. This ID must match the User ID in the user access token.
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 items per page. The default is 1.
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 Hype Train events. The list is empty if the broadcaster hasn’t run a Hype Train within the last 5 days.
id	String	An ID that identifies this event.
event_type	String	The type of event. The string is in the form, hypetrain.{event_name}. The request returns only progress event types (i.e., hypetrain.progression).
event_timestamp	String	The UTC date and time (in RFC3339 format) that the event occurred.
version	String	The version number of the definition of the event’s data. For example, the value is 1 if the data in `event_data` uses the first definition of the event’s data.
event_data	Object	The event’s data.
broadcaster_id	String	The ID of the broadcaster that’s running the Hype Train.
cooldown_end_time	string	The UTC date and time (in RFC3339 format) that another Hype Train can start.
expires_at	String	The UTC date and time (in RFC3339 format) that the Hype Train ends.
goal	Integer	The value needed to reach the next level.
id	String	An ID that identifies this Hype Train.
last_contribution	Object	The most recent contribution towards the Hype Train’s goal.
total	Integer	The total amount contributed. If `type` is BITS, `total` represents the amount of Bits used. If `type` is SUBS, `total` is 500, 1000, or 2500 to represent tier 1, 2, or 3 subscriptions, respectively.
type	String	The contribution method used. Possible values are: BITS — Cheering with Bits. SUBS — Subscription activity like subscribing or gifting subscriptions. OTHER — Covers other contribution methods not listed.
user	String	The ID of the user that made the contribution.
level	Integer	The highest level that the Hype Train reached (the levels are 1 through 5).
started_at	String	The UTC date and time (in RFC3339 format) that this Hype Train started.
top_contributions	Object[]	The top contributors for each contribution type. For example, the top contributor using BITS (by aggregate) and the top contributor using SUBS (by count).
total	Integer	The total amount contributed. If `type` is BITS, `total` represents the amount of Bits used. If `type` is SUBS, `total` is 500, 1000, or 2500 to represent tier 1, 2, or 3 subscriptions, respectively.
type	String	The contribution method used. Possible values are: BITS — Cheering with Bits. SUBS — Subscription activity like subscribing or gifting subscriptions. OTHER — Covers other contribution methods not listed.
user	String	The ID of the user that made the contribution.
total	Integer	The current total amount raised.
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	Description
200 OK	Successfully retrieved the broadcaster’s Hype Train events.
401 Unauthorized	The ID in broadcaster_id must match the user_id in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the channel:read:hype_train scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.

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

✎

Checks whether AutoMod would flag the specified message for review.

AutoMod is a moderation tool that holds inappropriate or harassing chat messages for moderators to review. Moderators approve or deny the messages that AutoMod flags; only approved messages are released to chat. AutoMod detects misspellings and evasive language automatically. For 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

Requires a user access token that includes the moderation:read scope.

URL

POST https://api.twitch.tv/helix/moderation/enforcements/status

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose AutoMod settings and list of blocked terms are used to check the message. This ID must match the user ID in the access token.

Request Body

Field	Type	Required?	Description
data	Object[]	Yes	The list of messages to check. The list must contain at least one message and may contain up to a maximum of 100 messages.
msg_id	String	Yes	A caller-defined ID used to correlate this message with the same message in the response.
msg_text	String	Yes	The message to check.

Response Body

Field	Type	Description
data	Object[]	The list of messages and whether Twitch would approve them for chat.
msg_id	String	The caller-defined ID passed in the request.
is_permitted	Boolean	A Boolean value that indicates whether Twitch would approve the message for chat or hold it for moderator review or block it from chat. Is true if Twitch would approve the message; otherwise, false if Twitch would hold the message for moderator review or block it from chat.

Response Codes

Code	Description
200 OK	Successfully checked the messages.
400 Bad Request	The broadcaster_id query parameter is required. The `data` field is required and the list must contain one or more messages to check. The `msg_id` field is required. The `msg_text` field is required.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include the moderation:read scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The ID in broadcaster_id must match the user ID in the user access token.
429 Too Many Requests	The broadcaster exceeded the number of chat message checks that they may make. See the endpoint's rate limits.

Example Request

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

{
  "data": [
    {
      "msg_id": "123",
      "is_permitted": true
    },
    {
      "msg_id": "393",
      "is_permitted": false
    }
  ]
}

Manage Held AutoMod Messages

✎

Allow or deny the message that AutoMod flagged for review. For information about AutoMod, see How to Use AutoMod.

To get messages that AutoMod is holding for review, subscribe to the automod-queue.<moderator_id>.<channel_id> topic using PubSub. PubSub sends a notification to your app when AutoMod holds a message for review.

Authorization

Requires a user access token that includes the moderator:manage:automod scope.

URL

POST https://api.twitch.tv/helix/moderation/automod/message

Request Body

Field	Type	Required?	Description
user_id	String	Yes	The moderator who is approving or denying the held message. This ID must match the user ID in the access token.
msg_id	String	Yes	The ID of the message to allow or deny.
action	String	Yes	The action to take for the message. Possible values are: ALLOW DENY

Response Codes

Code	Description
204 No Content	Successfully approved or denied the message.
400 Bad Request	The value in the `action` field is not valid. The `user_id` field is required. The `msg_id` field is required. The `action` field is required.
401 Unauthorized	The ID in `user_id` must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the moderator:manage:automod scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in user_id is not one of the broadcaster's moderators.
404 Not Found	The message specified in the `msg_id` field was not found.

Example Request

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

Get AutoMod Settings

✎

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

Authorization

Requires a user access token that includes the moderator:read:automod_settings scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose AutoMod settings you want to get.
moderator_id	String	Yes	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 in the user access token.

Response Body

Field	Type	Description
data	Object[]	The list of AutoMod settings. The list contains a single object that contains all the AutoMod settings.
broadcaster_id	String	The broadcaster’s ID.
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.
disability	Integer	The Automod level for discrimination against disability.
aggression	Integer	The Automod level for hostility involving aggression.
sexuality_sex_or_gender	Integer	The AutoMod level for discrimination based on sexuality, sex, or gender.
misogyny	Integer	The Automod level for discrimination against women.
bullying	Integer	The Automod level for hostility involving name calling or insults.
swearing	Integer	The Automod level for profanity.
race_ethnicity_or_religion	Integer	The Automod level for racial discrimination.
sex_based_terms	Integer	The Automod level for sexual content.

Response Codes

Code	Description
200 OK	Successfully retrieved the broadcaster’s AutoMod settings.
400 Bad Request	The broadcaster_id query parameter is required. The moderator_id query parameter is required.
401 Unauthorized	The ID in moderator_id must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the moderator:read:automod_settings scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in moderator_id is not one of the broadcaster's moderators.

Example Request

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

Shows what the response looks like if the broadcaster hasn’t enabled AutoMod (none of the settings are set).

{
  "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. The settings are used to automatically block inappropriate or harassing messages from appearing in the broadcaster’s chat room.

Authorization

Requires a user access token that includes the moderator:manage:automod_settings scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose AutoMod settings you want to update.
moderator_id	String	Yes	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 in the user access token.

Request Body

Because PUT is an overwrite operation, you must include all the fields that 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 may 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 necessarily 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.
broadcaster_id	String	The broadcaster’s ID.
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.
disability	Integer	The Automod level for discrimination against disability.
aggression	Integer	The Automod level for hostility involving aggression.
sexuality_sex_or_gender	Integer	The AutoMod level for discrimination based on sexuality, sex, or gender.
misogyny	Integer	The Automod level for discrimination against women.
bullying	Integer	The Automod level for hostility involving name calling or insults.
swearing	Integer	The Automod level for profanity.
race_ethnicity_or_religion	Integer	The Automod level for racial discrimination.
sex_based_terms	Integer	The Automod level for sexual content.

Response Codes

Code	Description
200 Ok	Successfully updated the broadcaster’s AutoMod settings.
400 Bad Request	The broadcaster_id is required. The moderator_id is required. The `overall_level` setting or one or more individual settings like `aggression` is required; the overall and individual settings are mutually exclusive, so don't set both. The value of one or more AutoMod settings is not valid.
401 Unauthorized	The ID in moderator_id must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the moderator:manage:automod_settings scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in moderator_id is not one of the broadcaster's moderators.

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

✎

Gets all users that the broadcaster banned or put in a timeout.

Authorization

Requires a user access token that includes the moderation:read or moderator:manage:banned_users scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose list of banned users you want to get. This ID must match the user ID in the access token.
user_id	String	No	A list of user IDs used to filter the results. To specify more than one ID, include this parameter for each user you want to get. For example, `user_id=1234&user_id=5678`. You may specify a maximum of 100 IDs. The returned list includes only those users that were banned or put in a timeout. The list is returned in the same order that you specified the IDs.
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 items per page. 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
before	String	No	The cursor used to get the previous 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 users that were banned or put in a timeout.
user_id	String	The ID of the banned user.
user_login	String	The banned user’s login name.
user_name	String	The banned user’s display name.
expires_at	String	The UTC date and time (in RFC3339 format) of when the timeout expires, or an empty string if the user is permanently banned.
created_at	String	The UTC date and time (in RFC3339 format) of when the user was banned.
reason	String	The reason the user was banned or put in a timeout if the moderator provided one.
moderator_id	String	The ID of the moderator that banned the user or put them in a timeout.
moderator_login	String	The moderator’s login name.
moderator_name	String	The moderator’s display 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	Description
200 OK	Successfully retrieved the list of banned users.
400 Bad Request	The broadcaster_id query parameter is required.
401 Unauthorized	The ID in broadcaster_id must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the moderation:read scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

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

Example Response

{
  "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 the specified broadcaster’s chat room or puts them in a timeout.

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

Authorization

Requires a user access token that includes the moderator:manage:banned_users scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose chat room the user is being banned from.
moderator_id	String	Yes	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 in the user access token.

Request Body

Field	Type	Required?	Description
data	Object	Yes	Identifies the user and type of ban.
user_id	String	Yes	The ID of the user to ban or put in a timeout.
duration	Integer	No	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 use the Unban user endpoint.
reason	String	No	The reason the you’re banning the user or putting them in a timeout. The text is user defined and is limited to a maximum of 500 characters.

Response Body

Field	Type	Description
data	Object[]	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.
moderator_id	String	The moderator that banned or put the user in the timeout.
user_id	String	The user that was banned or put in a timeout.
created_at	string	The UTC date and time (in RFC3339 format) that the ban or timeout was placed.
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 being put in a timeout.

Response Codes

Code	Description
200 OK	Successfully banned the user or placed them in a timeout.
400 Bad Request	The broadcaster_id query parameter is required. The moderator_id query parameter is required. The `user_id` field is required. The text in the `reason` field is too long. The value in the `duration` field is not valid. The user specified in the `user_id` field may not be banned. The user specified in the `user_id` field may not be put in a timeout. The user specified in the `user_id` field is already banned.
401 Unauthorized	The ID in moderator_id 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 moderator:manage:banned_users scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in moderator_id is not one of the broadcaster's moderators.
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	The app has exceeded the number of requests it may make per minute for this broadcaster.

Example Request 1

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

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

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.

To ban a user, see Ban user.

Authorization

Requires a user access token that includes the moderator:manage:banned_users scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose chat room the user is banned from chatting in.
moderator_id	String	Yes	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 in the user access token.
user_id	String	Yes	The ID of the user to remove the ban or timeout from.

Response Codes

Code	Description
204 No Content	Successfully removed the ban or timeout.
400 Bad Request	The broadcaster_id query parameter is required. The moderator_id query parameter is required. The user_id query parameter is required. The user specified in the user_id query parameter is not banned.
401 Unauthorized	The ID in moderator_id 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 moderator:manage:banned_users scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in moderator_id is not one of the broadcaster's moderators.
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	The app has exceeded the number of requests it may make per minute for this broadcaster.

Example Request 1

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=5432' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh'

Example Request 2

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 Unban Requests

✎

NEW Gets a list of unban requests for a broadcaster’s channel.

Authorization

Requires a user access token that includes the moderator:read:unban_requests or moderator:manage:unban_requests scope.
Query parameter moderator_id must match the user_id in the user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose channel is receiving unban requests.
moderator_id	String	Yes	The ID of the broadcaster or a user that has permission to moderate the broadcaster’s unban requests. This ID must match the user ID in the user access token.
status	String	Yes	Filter by a status. pending approved denied acknowledged canceled
user_id	String	No	The ID used to filter what unban requests are returned.
after	String	No	Cursor used to get next page of results. Pagination object in response contains cursor value.
first	Integer	No	The maximum number of items to return per page in response

Response Body

Field	Type	Description
data	Object[]	A list that contains information about the channel's unban requests.
id	String	Unban request ID.
broadcaster_id	String	User ID of broadcaster whose channel is receiving the unban request.
broadcaster_name	String	The broadcaster's display name.
broadcaster_login	String	The broadcaster's login name.
moderator_id	String	User ID of moderator who approved/denied the request.
moderator_login	String	The moderator's login name.
moderator_name	String	The moderator's display name.
user_id	String	User ID of the requestor who is asking for an unban.
user_login	String	The user's login name.
user_name	String	The user's display name.
text	String	Text of the request from the requesting user.
status	String	Status of the request. One of: pending approved denied acknowledged canceled
created_at	String	Timestamp of when the unban request was created.
resolved_at	String	Timestamp of when moderator/broadcaster approved or denied the request.
resolution_text	String	Text input by the resolver (moderator) of the unban. request
pagination	Object	Contains information used to page through a list of results. The object is empty if there are no more pages left to page through.
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

HTTP Code	Description
200 OK	Successfully retrieved the list of unban requests.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the broadcaster_id query parameter is not valid. The moderator_id query parameter is required. The ID in the moderator_id query parameter is not valid. The pagination cursor is not valid.
401 Unauthorized	The ID in moderator_id must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the moderator:read:unban_requests or moderator:manage:unban_requests scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets information about the specified broadcaster.

curl -X GET 'https://api.twitch.tv/helix/moderation/unban_requests?broadcaster_id=274637212&moderator_id=274637212&status=pending' \
​​​​​-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "92af127c-7326-4483-a52b-b0da0be61c01",
      "broadcaster_name": "torpedo09",
      "broadcaster_login": "torpedo09",
      "broadcaster_id": "274637212",
      "moderator_id": "141981764",
      "moderator_login": "twitchdev",
      "moderator_name": "TwitchDev",
      "user_id": "424596340",
      "user_login": "quotrok",
      "user_name": "quotrok",
      "text": "Please unban me from the channel?",
      "status": "pending",
      "created_at": "2022-08-07T02:07:55Z",
      "resolved_at": null,
      "resolution_text": null
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
  }
}

Resolve Unban Requests

✎

NEW Resolves an unban request by approving or denying it.

Authorization

Requires a user access token that includes the moderator:manage:unban_requests scope.
Query parameter moderator_id must match the user_id in theuser access token.

URL

PATCH https://api.twitch.tv/helix/moderation/unban_requests

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose channel is approving or denying the unban request.
moderator_id	String	Yes	The ID of the broadcaster or a user that has permission to moderate the broadcaster’s unban requests. This ID must match the user ID in the user access token.
unban_request_id	String	Yes	The ID of the broadcaster or a user that has permission to moderate the broadcaster’s unban requests. This ID must match the user ID in the user access token.
status	String	Yes	Resolution status. approved denied
resolution_text	String	No	Message supplied by the unban request resolver. The message is limited to a maximum of 500 characters.

Response Body

Field	Type	Description
data	Object[]
id	String	Unban request ID.
broadcaster_id	String	User ID of broadcaster whose channel is receiving the unban request.
broadcaster_login	String	The broadcaster’s login name.
broadcaster_name	String	The broadcaster’s display name.
moderator_id	String	User ID of moderator who approved/denied the request.
moderator_login	String	The moderator’s login name.
moderator_name	String	The moderator’s display name.
user_id	String	User ID of the requestor who is asking for an unban.
user_login	String	The user’s login name.
user_name	String	The user’s display name.
text	String	Text of the request from the requesting user.
status	String	Status of the request. One of: approved denied
created_at	String	Timestamp of when the unban request was created.
resolved_at	String	Timestamp of when moderator/broadcaster approved or denied the request.
resolution_text	String	Text input by the resolver (moderator) of the unban request.

Response Codes

HTTP Code	Description
200 OK	Successfully resolved the unban request.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the broadcaster_id query parameter is not valid. The moderator_id query parameter is required. The ID in the moderator_id query parameter is not valid. The pagination cursor is not valid. The broadcaster is not receiving unban requests Invalid requested update
401 Unauthorized	The ID in moderator_id must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the moderator:manage:unban_requests scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found	The unban request ID was not found.

Example Request

Approving an unban request.

curl -X PATCH 'https://api.twitch.tv/helix/moderation/unban_requests?broadcaster_id=274637212&moderator_id=274637212&unban_request_id=92af127c-7326-4483-a52b-b0daa0be61c01&status=approved' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'`

Example Response

{
  "data": [
    {
      "id": "92af127c-7326-4483-a52b-b0da0be61c01",
      "broadcaster_name": "torpedo09",
      "broadcaster_login": "torpedo09",
      "broadcaster_id": "274637212",
      "moderator_id": "141981764",
      "moderator_login": "twitchdev",
      "moderator_name": "TwitchDev",
      "user_id": "424596340",
      "user_login": "quotrok",
      "user_name": "quotrok",
      "text": "Please unban me from the channel?",
      "status": "approved",
      "created_at": "2022-08-07T02:07:55Z",
      "resolved_at": "2022-08-09T02:07:55Z",
      "resolution_text": null
    }
  ]
}

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 that includes the moderator:read:blocked_terms or moderator:manage:blocked_terms scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose blocked terms you’re getting.
moderator_id	String	Yes	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 in the user access token.
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 items per page. 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.

Response Body

Field	Type	Description
data	Object[]	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.
moderator_id	String	The moderator that blocked the word or phrase from being used in the broadcaster’s chat room.
id	String	An ID that identifies this blocked term.
text	String	The blocked word or phrase.
created_at	String	The UTC date and time (in RFC3339 format) that the term was blocked.
updated_at	String	The UTC date and time (in RFC3339 format) that 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.
expires_at	String	The UTC date and time (in RFC3339 format) that the blocked term is set to expire. After the block expires, users may 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.
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	Decription
200 OK	Successfully retrieved the list of blocked terms.
400 Bad Request	The broadcaster_id query parameter is required. The moderator_id query parameter is required.
401 Unauthorized	The ID in moderator_id must match the user ID in the user access token. The Authorization header must contain a user access token. The user access token must include the moderator:read:blocked_terms scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in moderator_id is not one of the broadcaster's moderators.

Example Request

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

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

Add Blocked Term

✎

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

Authorization

Requires a user access token that includes the moderator:manage:blocked_terms scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that owns the list of blocked terms.
moderator_id	String	Yes	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 in the user access token.

Request Body

Field	Type	Required?	Description
text	String	Yes	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 may include 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*. If the blocked term already exists, the response contains the existing blocked term.

Response Body

Field	Type	Description
data	Object[]	A list that contains the single blocked term that the broadcaster added.
broadcaster_id	String	The broadcaster that owns the list of blocked terms.
moderator_id	String	The moderator that blocked the word or phrase from being used in the broadcaster’s chat room.
id	String	An ID that identifies this blocked term.
text	String	The blocked word or phrase.
created_at	String	The UTC date and time (in RFC3339 format) that the term was blocked.
updated_at	String	The UTC date and time (in RFC3339 format) that 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.
expires_at	String	The UTC date and time (in RFC3339 format) that the blocked term is set to expire. After the block expires, users may 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.

Response Codes

Code	Decription
200 OK	Successfully retrieved the list of blocked terms.
400 Bad Request	The broadcaster_id query parameter is required. The moderator_id query parameter is required. The `text` field is required. The length of the term in the `text` field is either too short or too long.
401 Unauthorized	The ID in moderator_id must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the moderator:manage:blocked_terms scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in moderator_id is not one of the broadcaster's moderators.

Example Request 1

Adds a blocked term. Adding 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

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 from the broadcaster’s list of blocked terms.

Authorization

Requires a user access token that includes the moderator:manage:blocked_terms scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that owns the list of blocked terms.
moderator_id	String	Yes	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 in the user access token.
id	String	Yes	The ID of the blocked term to remove from the broadcaster’s list of blocked terms.

Response Codes

Code	Decription
204 No Content	Successfully removed the blocked term. Also returned if the ID is not found.
400 Bad Request	The broadcaster_id query parameter is required. The moderator_id query parameter is required. The id query parameter is required.
401 Unauthorized	The ID in moderator_id must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the moderator:manage:blocked_terms scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in moderator_id is not one of the broadcaster's moderators.

Example Request

Deletes the specified 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'

Delete Chat Messages

✎

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

Authorization

Requires a user access token that includes the moderator:manage:chat_messages scope.

URL

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

Request 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 the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.
message_id	String	No	The ID of the message to remove. The `id` tag in the PRIVMSG tag contains the message’s ID. 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 Codes

Code	Description
204 No Content	Successfully removed the specified messages.
400 Bad Request	You may not delete another moderator's messages. You may not delete the broadcaster's messages.
401 Unauthorized	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	The user in moderator_id is not one of the broadcaster's moderators.
404 Not Found	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 Moderated Channels

✎

Gets a list of channels that the specified user has moderator privileges in.

Authorization

Query parameter user_id must match the user ID in the User-Access token
Requires OAuth Scope: user:read:moderated_channels

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
user_id	String	Yes	A user’s ID. Returns the list of channels that this user has moderator privileges in. This ID must match the user ID in the user OAuth token
after	String	No	The cursor used to get the next page of results. The Pagination object in the response contains the cursor’s value.
first	Integer	No	The maximum number of items to return per page in the response. Minimum page size is 1 item per page and the maximum is 100. The default is 20.

Response Body

Field	Type	Description
data	Object[]	The list of channels that the user has moderator privileges in.
broadcaster_id	String	An ID that uniquely identifies the channel this user can moderate.
broadcaster_login	String	The channel’s login name.
broadcaster_name	String	The channels’ display 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.
cursor	String	The cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Example Request

curl -X GET 'https://api.twitch.tv/helix/moderation/channels?user_id=931931' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "broadcaster_id" : "12345",
      "broadcaster_login" : "grateful_broadcaster",
      "broadcaster_name" : "Grateful_Broadcaster"
    },
    {
      "broadcaster_id" : "98765",
      "broadcaster_login" : "bashfulgamer",
      "broadcaster_name" : "BashfulGamer"
    },
    ...
  ],
  "pagination" : {
    "cursor" : "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
  }
}

Get Moderators

✎

Gets all users allowed to moderate the broadcaster’s chat room.

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.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose list of moderators you want to get. This ID must match the user ID in the access token.
user_id	String	No	A list of user IDs used to filter the results. To specify more than one ID, include this parameter for each moderator you want to get. For example, `user_id=1234&user_id=5678`. You may specify a maximum of 100 IDs. The returned list includes only the users from the list who are moderators in the broadcaster’s channel. The list is returned in the same order as you specified the IDs.
first	String	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 items per page. 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 moderators.
user_id	String	The ID of the user that has permission to moderate the broadcaster’s channel.
user_login	String	The user’s login name.
user_name	String	The user’s display 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	Description
200 OK	Successfully retrieved the list of moderators.
400 Bad Request	The broadcaster_id query parameter is required.
401 Unauthorized	The ID in broadcaster_id must match the user ID found in the access token. The Authorization header is required and must contain a user access token. The user access token must include the moderation:read scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

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

✎

Adds a moderator to the broadcaster’s chat room.

Rate Limits: The broadcaster may add a maximum of 10 moderators within a 10-second window.

Authorization

Requires a user access token that includes the channel:manage:moderators scope.

URL

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

Request Query Parameters

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

Response Codes

Code	Description
204 No Content	Successfully added the moderator.
400 Bad Request	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 cannot become a moderator because they're banned from the channel.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include the channel:manage:moderators scope. The access 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 access 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 broadcaster has exceeded the number of requests allowed within a 10-second window. See this endpoint's rate limits.

Example Request

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

✎

Removes a moderator from the broadcaster’s chat room.

Rate Limits: The broadcaster may remove a maximum of 10 moderators within a 10-second window.

Authorization

Requires a user access token that includes the channel:manage:moderators scope.

URL

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

Request Query Parameters

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

Response Codes

Code	Description
204 No Content	Successfully removed the moderator.
400 Bad Request	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	The Authorization header is required and must contain a user access token. The user access token must include the channel:manage:moderators scope. The access 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 access token.
429 Too Many Requests	The broadcaster has exceeded the number of requests allowed within a 10-second window. See this endpoint's rate limits.

Example Request

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

✎

Gets a list of the broadcaster’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.

URL

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

Request 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 the ID of 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. This ID must match the user ID in the access token.
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 broadcaster doesn’t have VIP users.
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	Description
200 OK	Successfully retrieved the broadcaster’s list of VIPs.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the user_id query parameter is not valid. The number of user_id query parameters exceeds the maximum allowed.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include the channel:read:vips or 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.

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 Response

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

Add Channel VIP

✎

Adds the specified user as a VIP in the broadcaster’s channel.

Rate Limits: The broadcaster may add a maximum of 10 VIPs within a 10-second window.

Authorization

Requires a user access token that includes the channel:manage:vips scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
user_id	String	Yes	The ID of the user to give VIP status to.
broadcaster_id	String	Yes	The ID of the broadcaster that’s adding the user as a VIP. This ID must match the user ID in the access token.

Response Body

None

Response Codes

Code	Description
204 No Content	Successfully added the VIP.
400 Bad Request	The user in the user_id query parameter is blocked from the broadcaster's channel. The ID in the broadcaster_id query parameter is not valid. The ID in the user_id query parameter is not valid.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include 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.
403 Forbidden	The ID in the broadcaster_id query parameter must match the user ID in the access token.
404 Not Found	The ID in broadcaster_id was not found. The ID in user_id was not found.
409 Conflict	The broadcaster doesn’t have available VIP slots. Read More
422 Unprocessable Entity	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 broadcaster exceeded the number of VIP that they may add within a 10-second window. 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

✎

Removes the specified user as a VIP in the broadcaster’s channel.

If the broadcaster is removing the user’s VIP status, the ID in the broadcaster_id query parameter must match the user ID in the access token; otherwise, if the user is removing their VIP status themselves, the ID in the user_id query parameter must match the user ID in the access token.

Rate Limits: The broadcaster may remove a maximum of 10 VIPs within a 10-second window.

Authorization

Requires a user access token that includes the channel:manage:vips scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
user_id	String	Yes	The ID of the user to remove VIP status from.
broadcaster_id	String	Yes	The ID of the broadcaster who owns the channel where the user has VIP status.

Response Body

None

Response Codes

Code	Description
204 No Content	Successfully removed the VIP status from the user.
400 Bad Request	The ID in broadcaster_id is not valid. The ID in user_id is not valid.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include 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.
403 Forbidden	The user in broadcaster_id doesn't have permission to remove the user's VIP status.
404 Not Found	The ID in broadcaster_id was not found. The ID in user_id was not found.
422 Unprocessable Entity	The user in user_id is not a VIP in the broadcaster's channel.
429 Too Many Requests	The broadcaster exceeded the number of VIPs that they may remove within a 10-second window. See Rate Limits for this endpoint above.

Example Request

Removes the VIP user from the broadcaster’s channel.

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

Update Shield Mode Status

✎

Activates or deactivates the broadcaster’s Shield Mode.

Twitch’s Shield Mode feature is like a panic button that broadcasters can push to protect themselves from chat abuse coming from one or more accounts. When activated, Shield Mode applies the overrides that the broadcaster configured in the Twitch UX. If the broadcaster hasn’t configured Shield Mode, it applies default overrides.

Authorization

Requires a user access token that includes the moderator:manage:shield_mode scope.

URL

PUT https://api.twitch.tv/helix/moderation/shield_mode

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose Shield Mode you want to activate or deactivate.
moderator_id	String	Yes	The ID of the broadcaster or a user that is one of the broadcaster’s moderators. This ID must match the user ID in the access token.

Request Body

Field	Type	Required?	Description
is_active	Boolean	Yes	A Boolean value that determines whether to activate Shield Mode. Set to true to activate Shield Mode; otherwise, false to deactivate Shield Mode.

Response Body

Field	Type	Description
data	Object[]	A list that contains a single object with the broadcaster’s updated Shield Mode status.
is_active	Boolean	A Boolean value that determines whether Shield Mode is active. Is true if Shield Mode is active; otherwise, false.
moderator_id	String	An ID that identifies the moderator that last activated Shield Mode.
moderator_login	String	The moderator’s login name.
moderator_name	String	The moderator’s display name.
last_activated_at	String	The UTC timestamp (in RFC3339 format) of when Shield Mode was last activated.

Response Codes

Code	Description
200 OK	Successfully updated the broadcaster’s Shield Mode status.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the broadcaster_id query parameter is not valid. The `is_active` field is required. The value in the `is_active` field is not valid.
401 Unauthorized	The ID in moderator_id must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the moderator:manage:shield_mode scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in moderator_id is not one of the broadcaster's moderators.

Example Request

curl -X PUT 'https://api.twitch.tv/helix/moderation/shield_mode?broadcaster_id=12345&moderator_id=98765' \
-H 'Authorization: Bearer kpvy3cjboypmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0yan9c87zr6t' \
-H 'Content-Type: application/json' \
-d '{"is_active":false}'

Example Response

{
  "data": [
    {
      "is_active": false,
      "moderator_id": "98765",
      "moderator_name": "SimplySimple",
      "moderator_login": "simplysimple",
      "last_activated_at": "2022-07-26T17:16:03.123Z"
    }
  ]
}

Get Shield Mode Status

✎

Gets the broadcaster’s Shield Mode activation status.

To receive notification when the broadcaster activates and deactivates Shield Mode, subscribe to the channel.shield_mode.begin and channel.shield_mode.end subscription types.

Authorization

Requires a user access token that includes the moderator:read:shield_mode or moderator:manage:shield_mode scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose Shield Mode activation status you want to get.
moderator_id	String	Yes	The ID of the broadcaster or a user that is one of the broadcaster’s moderators. This ID must match the user ID in the access token.

Response Body

Field	Type	Description
data	Object[]	A list that contains a single object with the broadcaster’s Shield Mode status.
is_active	Boolean	A Boolean value that determines whether Shield Mode is active. Is true if the broadcaster activated Shield Mode; otherwise, false.
moderator_id	String	An ID that identifies the moderator that last activated Shield Mode. Is an empty string if Shield Mode hasn’t been previously activated.
moderator_login	String	The moderator’s login name. Is an empty string if Shield Mode hasn’t been previously activated.
moderator_name	String	The moderator’s display name. Is an empty string if Shield Mode hasn’t been previously activated.
last_activated_at	String	The UTC timestamp (in RFC3339 format) of when Shield Mode was last activated. Is an empty string if Shield Mode hasn’t been previously activated.

Response Codes

Code	Description
200 OK	Successfully retrieved the broadcaster’s Shield Mode activation status.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the broadcaster_id query parameter is not valid.
401 Unauthorized	The ID in moderator_id must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the moderator:read:shield_mode or moderator:manage:shield_mode scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in moderator_id is not one of the broadcaster's moderators.

Example Request

curl -X GET 'https://api.twitch.tv/helix/moderation/shield_mode?broadcaster_id=12345&moderator_id=98765' \
-H 'Authorization: Bearer kpvy3cjboypmiacwr0c19hotn5s' \
-H 'Client-Id: hof5gwx0su6owfn0yan9c87zr6t'

Example Response

{
  "data": [
    {
      "is_active": true,
      "moderator_id": "98765",
      "moderator_name": "SimplySimple",
      "moderator_login": "simplysimple",
      "last_activated_at": "2022-07-26T17:16:03.123Z"
    }
  ]
}

Warn Chat User

✎

NEW Warns a user in the specified broadcaster’s chat room, preventing them from chat interaction until the warning is acknowledged. New warnings can be issued to a user when they already have a warning in the channel (new warning will replace old warning).

Authorization

Requires a user access token that includes the moderator:manage:warnings scope. Query parameter moderator_id must match the user_id in the user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the channel in which the warning will take effect.
moderator_id	String	Yes	The ID of the twitch user who requested the warning.

Request Body

Parameter	Type	Required?	Description
data	Object	Yes	A list that contains information about the warning.
user_id	String	Yes	The ID of the twitch user to be warned.
reason	String	Yes	A custom reason for the warning. Max 500 chars.

Response Body

Field	Type	Description
data	Object[]	A list that contains information about the warning.
broadcaster_id	String	The ID of the channel in which the warning will take effect.
user_id	String	The ID of the warned user.
moderator_id	String	The ID of the user who applied the warning.
reason	String	The reason provided for warning.

Response Codes

Code	Description
200 OK	Successfully warn a user.
400 Bad Request	The broadcaster_id query parameter is required. The moderator_id query parameter is required. The user_id query parameter is required. The reason query parameter is required. The text in the reason field is too long. The user specified in the user_id may not be warned.
401 Unauthorized	The ID in moderator_id must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the moderator:manage:warnings scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in moderator_id is not one of the broadcaster’s moderators.
409 Conflict	You may not update the user’s warning state while someone else is updating the state. For example, someone else is currently warning the user or the user is acknowledging an existing warning. Please retry your request.
429 Too Many Requests	The app has exceeded the number of requests it may make per minute for this broadcaster.
500 Internal Server Error	Internal Server Error.

Example Request

curl -X POST  'https://api.twitch.tv/helix/moderation/warnings?broadcaster_id=404040&moderator_id=404041' \
-H 'Authorization: Bearer 4a4x78f5wqvkybms7mxfist3jmzul' \
-H 'Client-Id: t214nt8z1rdtbj69hyarjvh5mi6fh' \
-H 'Content-Type: application/json' \
-d '{"data": {"user_id":"9876","reason":"stop doing that!"}}'

Example Response

{
  "data": [
    {
      "broadcaster_id": "404040",
      "user_id": "9876",
      "moderator_id": "404041",
      "reason": "stop doing that!"
    }
  ]
}

Get Polls

✎

Gets a list of polls that the broadcaster created.

Polls are available for 90 days after they’re created.

Authorization

Requires a user access token that includes the channel:read:polls or channel:manage:polls scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that created the polls. This ID must match the user ID in the user access token.
id	String	No	A list of IDs that identify the polls to return. To specify more than one ID, include this parameter for each poll you want to get. For example, `id=1234&id=5678`. You may specify a maximum of 20 IDs. Specify this parameter only if you want to filter the list that the request returns. The endpoint ignores duplicate IDs and those not owned by this broadcaster.
first	String	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 20 items per page. 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[]	A list of polls. The polls are returned in descending order of start time unless you specify IDs in the request, in which case they're returned in the same order as you passed them in the request. The list is empty if the broadcaster hasn't created polls.
id	String	An ID that identifies the poll.
broadcaster_id	String	An ID that identifies the broadcaster that created the poll.
broadcaster_name	String	The broadcaster's display name.
broadcaster_login	String	The broadcaster's login name.
title	String	The question that viewers are voting on. For example, What game should I play next? The title may contain a maximum of 60 characters.
choices	Object[]	A list of choices that viewers can choose from. The list will contain a minimum of two choices and up to a maximum of five choices.
id	String	An ID that identifies this choice.
title	String	The choice's title. The title may contain a maximum of 25 characters.
votes	Integer	The total number of votes cast for this choice.
channel_points_votes	Integer	The number of votes cast using Channel Points.
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	A Boolean value that indicates whether viewers may cast additional votes using Channel Points. For information about Channel Points, see Channel Points Guide.
channel_points_per_vote	Integer	The number of points the viewer must spend to cast one additional vote.
status	String	The poll's status. Valid values are: ACTIVE — The poll is running. COMPLETED — The poll ended on schedule (see the `duration` field). TERMINATED — The poll was terminated before its scheduled end. ARCHIVED — The poll has been archived and is no longer visible on the channel. MODERATED — The poll was deleted. INVALID — Something went wrong while determining the state.
duration	Integer	The length of time (in seconds) that the poll will run for.
started_at	String	The UTC date and time (in RFC3339 format) of when the poll began.
ended_at	String	The UTC date and time (in RFC3339 format) of when the poll ended. If `status` is ACTIVE, this field is set to null.
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	Description
200 OK	Successfully retrieved the broadcaster's polls.
400 Bad Request	The broadcaster_id query parameter is required.
401 Unauthorized	The ID in broadcaster_id 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 is missing the channel:read:polls scope. The access token is not valid. The client ID specified in the Client-Id header must match the client ID specified in the access token.
404 Not Found	None of the IDs in the id query parameters were found.

Example Request

Gets the specified broadcaster’s list of polls.

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

✎

Creates a poll that viewers in the broadcaster’s channel can vote on.

The poll begins as soon as it’s created. You may run only one poll at a time.

Authorization

Requires a user access token that includes the channel:manage:polls scope.

URL

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

Request Body

Field	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that’s running the poll. This ID must match the user ID in the user access token.
title	String	Yes	The question that viewers will vote on. For example, What game should I play next? The question may contain a maximum of 60 characters.
choices	Object[]	Yes	A list of choices that viewers may choose from. The list must contain a minimum of 2 choices and up to a maximum of 5 choices.
title	String	Yes	One of the choices the viewer may select. The choice may contain a maximum of 25 characters.
duration	Integer	Yes	The length of time (in seconds) that the poll will run for. The minimum is 15 seconds and the maximum is 1800 seconds (30 minutes).
channel_points_voting_enabled	Boolean	No	A Boolean value that indicates whether viewers may cast additional votes using Channel Points. If true, the viewer may cast more than one vote but each additional vote costs the number of Channel Points specified in `channel_points_per_vote`. The default is false (viewers may cast only one vote). For information about Channel Points, see Channel Points Guide.
channel_points_per_vote	Integer	No	The number of points that the viewer must spend to cast one additional vote. The minimum is 1 and the maximum is 1000000. Set only if `ChannelPointsVotingEnabled` is true.

Response Body

Field	Type	Description
data	Object[]	A list that contains the single poll that you created.
id	String	An ID that identifies the poll.
broadcaster_id	String	An ID that identifies the broadcaster that created the poll.
broadcaster_name	String	The broadcaster’s display name.
broadcaster_login	String	The broadcaster’s login name.
title	String	The question that viewers are voting on. For example, What game should I play next? The title may contain a maximum of 60 characters.
choices	Object[]	A list of choices that viewers can choose from. The list will contain a minimum of two choices and up to a maximum of five choices.
id	String	An ID that identifies this choice.
title	String	The choice’s title. The title may contain a maximum of 25 characters.
votes	Integer	The total number of votes cast for this choice.
channel_points_votes	Integer	The number of votes cast using Channel Points.
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	A Boolean value that indicates whether viewers may cast additional votes using Channel Points. For information about Channel Points, see Channel Points Guide.
channel_points_per_vote	Integer	The number of points the viewer must spend to cast one additional vote.
status	String	The poll’s status. Valid values are: ACTIVE — The poll is running. COMPLETED — The poll ended on schedule (see the `duration` field). TERMINATED — The poll was terminated before its scheduled end. ARCHIVED — The poll has been archived and is no longer visible on the channel. MODERATED — The poll was deleted. INVALID — Something went wrong while determining the state.
duration	Integer	The length of time (in seconds) that the poll will run for.
started_at	String	The UTC date and time (in RFC3339 format) of when the poll began.
ended_at	String	The UTC date and time (in RFC3339 format) of when the poll ended. If `status` is ACTIVE, this field is set to null.

Response Codes

Code	Description
200 OK	Successfully created the poll.
400 Bad Request	The `broadcaster_id` field is required. The `title` field is required. The `choices` field is required. The `duration` field is required. The value in `duration` is outside the allowed range of values. The value in `channel_points_per_vote` is outside the allowed range of values. The value in `bits_per_vote` is outside the allowed range of values. The poll's `title` is too long. The choice's `title` is too long. The choice's `title` failed AutoMod checks. The number of choices in the poll may not be less than 2 or greater that 5. The broadcaster already has a poll that's running; you may not create another poll until the current poll completes.
401 Unauthorized	The ID in `broadcaster_id` 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 is missing the channel:manage:polls scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Creates a poll for the specified broadcaster.

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

✎

Ends an active poll. You have the option to end it or end it and archive it.

Authorization

Requires a user access token that includes the channel:manage:polls scope.

URL

PATCH https://api.twitch.tv/helix/polls

Request Body

Field	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that’s running the poll. This ID must match the user ID in the user access token.
id	String	Yes	The ID of the poll to update.
status	String	Yes	The status to set the poll to. Possible case-sensitive values are: TERMINATED — Ends the poll before the poll is scheduled to end. The poll remains publicly visible. ARCHIVED — Ends the poll before the poll is scheduled to end, and then archives it so it's no longer publicly visible.

Response Body

Field	Type	Description
data	Object[]	A list that contains the poll that you ended.
id	String	An ID that identifies the poll.
broadcaster_id	String	An ID that identifies the broadcaster that created the poll.
broadcaster_name	String	The broadcaster’s display name.
broadcaster_login	String	The broadcaster’s login name.
title	String	The question that viewers are voting on. For example, What game should I play next? The title may contain a maximum of 60 characters.
choices	Object[]	A list of choices that viewers can choose from. The list will contain a minimum of two choices and up to a maximum of five choices.
id	String	An ID that identifies this choice.
title	String	The choice’s title. The title may contain a maximum of 25 characters.
votes	Integer	The total number of votes cast for this choice.
channel_points_votes	Integer	The number of votes cast using Channel Points.
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	A Boolean value that indicates whether viewers may cast additional votes using Channel Points. For information about Channel Points, see Channel Points Guide.
channel_points_per_vote	Integer	The number of points the viewer must spend to cast one additional vote.
status	String	The poll’s status. Valid values are: ACTIVE — The poll is running. COMPLETED — The poll ended on schedule (see the `duration` field). TERMINATED — The poll was terminated before its scheduled end. ARCHIVED — The poll has been archived and is no longer visible on the channel. MODERATED — The poll was deleted. INVALID — Something went wrong while determining the state.
duration	Integer	The length of time (in seconds) that the poll will run for.
started_at	String	The UTC date and time (in RFC3339 format) of when the poll began.
ended_at	String	The UTC date and time (in RFC3339 format) of when the poll ended. If `status` is ACTIVE, this field is set to null.

Response Codes

Code	Description
200 OK	Successfully ended the poll.
400 Bad Request	The `broadcaster_id` field is required. The `id` field is required. The `status` field is required. The value in the `status` field is not valid. The poll must be active to terminate or archive it.
401 Unauthorized	The ID in `broadcaster_id` must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the channel:manage:polls scope. The access token is not valid. The client ID specified in the Client-Id header must match the client ID specified in the access token.

Example Request

Ends the specific poll, 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

✎

Gets a list of Channel Points Predictions that the broadcaster created.

Authorization

Requires a user access token that includes the channel:read:predictions or channel:manage:predictions scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose predictions you want to get. This ID must match the user ID in the user access token.
id	String	No	The ID of the prediction to get. To specify more than one ID, include this parameter for each prediction you want to get. For example, `id=1234&id=5678`. You may specify a maximum of 25 IDs. The endpoint ignores duplicate IDs and those not owned by the broadcaster.
first	String	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 25 items per page. 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 broadcaster’s list of Channel Points Predictions. The list is sorted in descending ordered by when the prediction began (the most recent prediction is first). The list is empty if the broadcaster hasn’t created predictions.
id	String	An ID that identifies this prediction.
broadcaster_id	String	An ID that identifies the broadcaster that created the prediction.
broadcaster_name	String	The broadcaster’s display name.
broadcaster_login	String	The broadcaster’s login name.
title	String	The question that the prediction asks. For example, Will I finish this entire pizza?
winning_outcome_id	String	The ID of the winning outcome. Is null unless `status` is RESOLVED.
outcomes	Object[]	The list of possible outcomes for the prediction.
id	String	An ID that identifies this outcome.
title	String	The outcome’s text.
users	Integer	The number of unique viewers that chose this outcome.
channel_points	Integer	The number of Channel Points spent by viewers on this outcome.
top_predictors	Object[]	A list of viewers who were the top predictors; otherwise, null if none.
user_id	String	An ID that identifies the viewer.
user_name	String	The viewer’s display name.
user_login	String	The viewer’s login name.
channel_points_used	Integer	The number of Channel Points the viewer spent.
channel_points_won	Integer	The number of Channel Points distributed to the viewer.
color	String	The color that visually identifies this outcome in the UX. Possible values are: BLUE PINK If the number of outcomes is two, the color is BLUE for the first outcome and PINK for the second outcome. If there are more than two outcomes, the color is BLUE for all outcomes.
prediction_window	Integer	The length of time (in seconds) that the prediction will run for.
status	String	The prediction’s status. Valid values are: ACTIVE — The Prediction is running and viewers can make predictions. CANCELED — The broadcaster canceled the Prediction and refunded the Channel Points to the participants. LOCKED — The broadcaster locked the Prediction, which means viewers can no longer make predictions. RESOLVED — The winning outcome was determined and the Channel Points were distributed to the viewers who predicted the correct outcome.
created_at	String	The UTC date and time of when the Prediction began.
ended_at	String	The UTC date and time of when the Prediction ended. If `status` is ACTIVE, this is set to null.
locked_at	String	The UTC date and time of when the Prediction was locked. If `status` is not LOCKED, this is set to null.
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	Description
200 OK	Successfully retrieved the list of predictions.
400 Bad Request	The broadcaster_id query parameter is required.
401 Unauthorized	The ID in broadcaster_id 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:predictions scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets the specified broadcaster’s list of predictions.

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

✎

Creates a Channel Points Prediction.

With a Channel Points Prediction, the broadcaster poses a question and viewers try to predict the outcome. The prediction runs as soon as it’s created. The broadcaster may run only one prediction at a time.

Authorization

Requires a user access token that includes the channel:manage:predictions scope.

URL

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

Request Body

Field	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that’s running the prediction. This ID must match the user ID in the user access token.
title	String	Yes	The question that the broadcaster is asking. For example, Will I finish this entire pizza? The title is limited to a maximum of 45 characters.
outcomes	Object[]	Yes	The list of possible outcomes that the viewers may choose from. The list must contain a minimum of 2 choices and up to a maximum of 10 choices.
title	String	Yes	The text of one of the outcomes that the viewer may select. The title is limited to a maximum of 25 characters.
prediction_window	Integer	Yes	The length of time (in seconds) that the prediction will run for. The minimum is 30 seconds and the maximum is 1800 seconds (30 minutes).

Response Body

Field	Type	Description
data	Object[]	A list that contains the single prediction that you created.
id	String	An ID that identifies this prediction.
broadcaster_id	String	An ID that identifies the broadcaster that created the prediction.
broadcaster_name	String	The broadcaster’s display name.
broadcaster_login	String	The broadcaster’s login name.
title	String	The question that the prediction asks. For example, Will I finish this entire pizza?
winning_outcome_id	String	The ID of the winning outcome. Is null unless `status` is RESOLVED.
outcomes	Object[]	The list of possible outcomes for the prediction.
id	String	An ID that identifies this outcome.
title	String	The outcome’s text.
users	Integer	The number of unique viewers that chose this outcome.
channel_points	Integer	The number of Channel Points spent by viewers on this outcome.
top_predictors	Object[]	A list of viewers who were the top predictors; otherwise, null if none.
user_id	String	An ID that identifies the viewer.
user_name	String	The viewer’s display name.
user_login	String	The viewer’s login name.
channel_points_used	Integer	The number of Channel Points the viewer spent.
channel_points_won	Integer	The number of Channel Points distributed to the viewer.
color	String	The color that visually identifies this outcome in the UX. Possible values are: BLUE PINK If the number of outcomes is two, the color is BLUE for the first outcome and PINK for the second outcome. If there are more than two outcomes, the color is BLUE for all outcomes.
prediction_window	Integer	The length of time (in seconds) that the prediction will run for.
status	String	The prediction’s status. Valid values are: ACTIVE — The Prediction is running and viewers can make predictions. CANCELED — The broadcaster canceled the Prediction and refunded the Channel Points to the participants. LOCKED — The broadcaster locked the Prediction, which means viewers can no longer make predictions. RESOLVED — The winning outcome was determined and the Channel Points were distributed to the viewers who predicted the correct outcome.
created_at	String	The UTC date and time of when the Prediction began.
ended_at	String	The UTC date and time of when the Prediction ended. If `status` is ACTIVE, this is set to null.
locked_at	String	The UTC date and time of when the Prediction was locked. If `status` is not LOCKED, this is set to null.

Response Codes

Code	Description
200 OK	Successfully created the Channel Points Prediction.
400 Bad Request	The `broadcaster_id` field is required. The `title` field is required. The `outcomes` field is required. The `prediction_window` field is required. The value in `prediction_window` is outside the allowed range of values. The prediction's `title` is too long. The outcome's `title` is too long. The outcome's `title` failed AutoMod checks. There must be 2 outcomes in the prediction. The broadcaster already has a prediction that's running; you may not create another prediction until the current prediction is resolved or canceled.
401 Unauthorized	The ID in `broadcaster_id` 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:manage:predictions scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
429 Too Many Requests

Example Request

Creates a Channel Points Prediction for the specified broadcaster.

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

✎

Locks, resolves, or cancels a Channel Points Prediction.

Authorization

Requires a user access token that includes the channel:manage:predictions scope.

URL

PATCH https://api.twitch.tv/helix/predictions

Request Body

Field	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that’s running the prediction. This ID must match the user ID in the user access token.
id	String	Yes	The ID of the prediction to update.
status	String	Yes	The status to set the prediction to. Possible case-sensitive values are: RESOLVED — The winning outcome is determined and the Channel Points are distributed to the viewers who predicted the correct outcome. CANCELED — The broadcaster is canceling the prediction and sending refunds to the participants. LOCKED — The broadcaster is locking the prediction, which means viewers may no longer make predictions. The broadcaster can update an active prediction to LOCKED, RESOLVED, or CANCELED; and update a locked prediction to RESOLVED or CANCELED. The broadcaster has up to 24 hours after the prediction window closes to resolve the prediction. If not, Twitch sets the status to CANCELED and returns the points.
winning_outcome_id	String	No	The ID of the winning outcome. You must set this parameter if you set `status` to RESOLVED.

Response Body

Field	Type	Description
data	Object[]	A list that contains the single prediction that you updated.
id	String	An ID that identifies this prediction.
broadcaster_id	String	An ID that identifies the broadcaster that created the prediction.
broadcaster_name	String	The broadcaster’s display name.
broadcaster_login	String	The broadcaster’s login name.
title	String	The question that the prediction asks. For example, Will I finish this entire pizza?
winning_outcome_id	String	The ID of the winning outcome. Is null unless `status` is RESOLVED.
outcomes	Object[]	The list of possible outcomes for the prediction.
id	String	An ID that identifies this outcome.
title	String	The outcome’s text.
users	Integer	The number of unique viewers that chose this outcome.
channel_points	Integer	The number of Channel Points spent by viewers on this outcome.
top_predictors	Object[]	A list of viewers who were the top predictors; otherwise, null if none.
user_id	String	An ID that identifies the viewer.
user_name	String	The viewer’s display name.
user_login	String	The viewer’s login name.
channel_points_used	Integer	The number of Channel Points the viewer spent.
channel_points_won	Integer	The number of Channel Points distributed to the viewer.
color	String	The color that visually identifies this outcome in the UX. Possible values are: BLUE PINK If the number of outcomes is two, the color is BLUE for the first outcome and PINK for the second outcome. If there are more than two outcomes, the color is BLUE for all outcomes.
prediction_window	Integer	The length of time (in seconds) that the prediction will run for.
status	String	The prediction’s status. Valid values are: ACTIVE — The Prediction is running and viewers can make predictions. CANCELED — The broadcaster canceled the Prediction and refunded the Channel Points to the participants. LOCKED — The broadcaster locked the Prediction, which means viewers can no longer make predictions. RESOLVED — The winning outcome was determined and the Channel Points were distributed to the viewers who predicted the correct outcome.
created_at	String	The UTC date and time of when the Prediction began.
ended_at	String	The UTC date and time of when the Prediction ended. If `status` is ACTIVE, this is set to null.
locked_at	String	The UTC date and time of when the Prediction was locked. If `status` is not LOCKED, this is set to null.

Response Codes

Code	Description
200 OK	Successfully ended the prediction.
400 Bad Request	The `broadcaster_id` field is required. The `id` field is required. The `status` field is required. The `winning_outcome_id` field is required if `status` is RESOLVED. The value in the `status` field is not valid. To update the prediction's status to RESOLVED or CANCELED, its current status must be ACTIVE or LOCKED. To update the prediction's status to LOCKED, its current status must be ACTIVE.
401 Unauthorized	The ID in `broadcaster_id` must match the user ID in the OAuth token. The Authorization header is required and must contain a user access token. The user access token must include the channel:manage:predictions scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found	The prediction in the `id` field was not found. The outcome in the `winning_outcome_id` field was not found.

Example Request

Resolves the specified Channel Points Prediction.

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

✎

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 determine whether the raid successfully occurred, you must subscribe to the Channel Raid event. For more information, see Get notified when a raid begins.

To cancel a pending raid, use the Cancel a raid endpoint.

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.

URL

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

Request Query Parameters

Parameter	Type	Required ?	Description
from_broadcaster_id	String	Yes	The ID of the broadcaster that’s sending the raiding party. This ID must match the user ID in the user access token.
to_broadcaster_id	String	Yes	The ID of the broadcaster to raid.

Response Body

Field	Type	Description
data	Object[]	A list that contains a single object with information about the pending raid.
created_at	String	The UTC date and time, in RFC3339 format, of when the raid was requested.
is_mature	Boolean	A Boolean value that indicates whether the channel being raided contains mature content.

Response Codes

Code	Description
200 OK	Successfully requested to start a raid. To determine whether the raid successfully occurred (that is, the broadcaster clicked Raid Now or the countdown expired), you must subscribe to the Channel Raid event.
400 Bad Request	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. The ID in the to_broadcaster_id query parameter is not valid.
401 Unauthorized	The ID in from_broadcaster_id must match the user ID found in the request’s OAuth token. The Authorization header is required and must contain a user access token. The user access token must include the channel:manage:raids scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found	The targeted channel was not found.
409 Conflict	The broadcaster is already in the process of raiding another channel.
429 Too Many Requests	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

✎

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

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that initiated the raid. This ID must match the user ID in the user access token.

Response Codes

Code	Description
204 No Content	The pending raid was successfully canceled.
400 Bad Request	The ID in the broadcaster_id query parameter is not valid.
401 Unauthorized	The ID in broadcaster_id must match the user ID found in the request’s OAuth token. The Authorization header is required and must contain a user access token. The user access token must include the channel:manage:raids scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found	The broadcaster doesn't have a pending raid to cancel.
429 Too Many Requests	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 the broadcaster’s streaming schedule. You can get the entire schedule or specific segments of the schedule. Learn More

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that owns the streaming schedule you want to get.
id	String	No	The ID of the scheduled segment to return. To specify more than one segment, include the ID of each segment you want to get. For example, `id=1234&id=5678`. You may specify a maximum of 100 IDs.
start_time	String	No	The UTC date and time that identifies when in the broadcaster’s schedule to start returning segments. If not specified, the request returns segments starting after the current UTC date and time. Specify the date and time in RFC3339 format (for example, `2022-09-01T00:00:00Z`).
utc_offset	String	No	Not supported.
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 25 items per page. 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 broadcaster’s streaming schedule.
segments	Object[]	The list of broadcasts in the broadcaster’s streaming schedule.
id	String	An ID that identifies this broadcast segment.
start_time	String	The UTC date and time (in RFC3339 format) of when the broadcast starts.
end_time	String	The UTC date and time (in RFC3339 format) of when the broadcast ends.
title	String	The broadcast segment’s title.
canceled_until	String	Indicates whether the broadcaster canceled this segment of a recurring broadcast. If the broadcaster canceled this segment, this field is set to the same value that’s in the `end_time` field; otherwise, it’s set to null.
category	Object	The type of content that the broadcaster plans to stream or null if not specified.
id	String	An ID that identifies the category that best represents the content that the broadcaster plans to stream. For example, the game’s ID if the broadcaster will play a game or the Just Chatting ID if the broadcaster will host a talk show.
name	String	The name of the category. For example, the game’s title if the broadcaster will playing a game or Just Chatting if the broadcaster will host a talk show.
is_recurring	Boolean	A Boolean value that determines whether the broadcast is part of a recurring series that streams at the same time each week or is a one-time broadcast. Is true if the broadcast is part of a recurring series.
broadcaster_id	String	The ID of the broadcaster that owns the broadcast schedule.
broadcaster_name	String	The broadcaster’s display name.
broadcaster_login	String	The broadcaster’s login name.
vacation	Object	The dates when the broadcaster is on vacation and not streaming. Is set to null if vacation mode is not enabled.
start_time	String	The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation starts.
end_time	String	The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation ends.
pagination	Object	The information used to page through a 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. Set the request’s after query parameter to this value.

Response Codes

Code	Description
200 OK	Successfully retrieved the broadcaster’s streaming schedule.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the broadcaster_id query parameter is not valid. The ID in the id query parameter is not valid. The format of the date and time in the start_time query parameter is not valid.
401 Unauthorized	The Authorization header is required and must specify a valid app access token or user access token. The access token is not valid. The ID in the Client-Id header must match the Client ID in the access token.
403 Forbidden	Only partners and affiliates may add non-recurring broadcast segments.
404 Not Found	The broadcaster has not created a streaming schedule.

Example Request

Gets the specified broadcaster’s streaming 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 the broadcaster’s streaming schedule as an iCalendar.

Authorization

The Client-Id and Authorization headers are not required.

URL

GET https://api.twitch.tv/helix/schedule/icalendar

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that owns the streaming schedule you want to get.

Response Body

The response body contains the iCalendar data (see RFC5545).

The Content-Type response header is set to text/calendar.

Response Codes

Code	Description
200 OK	Successfully retrieved the broadcaster’s schedule as an iCalendar.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the broadcaster_id query parameter is not valid.

Example Request

Gets the specified broadcaster’s streaming 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

✎

Updates the broadcaster’s schedule settings, such as scheduling a vacation.

Authorization

Requires a user access token that includes the channel:manage:schedule scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose schedule settings you want to update. The ID must match the user ID in the user access token.
is_vacation_enabled	Boolean	No	A Boolean value that indicates whether the broadcaster has scheduled a vacation. Set to true to enable Vacation Mode and add vacation dates, or false to cancel a previously scheduled vacation.
vacation_start_time	String	No	The UTC date and time of when the broadcaster’s vacation starts. Specify the date and time in RFC3339 format (for example, 2021-05-16T00:00:00Z). Required if is_vacation_enabled is true.
vacation_end_time	String	No	The UTC date and time of when the broadcaster’s vacation ends. Specify the date and time in RFC3339 format (for example, 2021-05-30T23:59:59Z). Required if is_vacation_enabled is true.
timezone	String	No	The time zone that the broadcaster broadcasts from. Specify the time zone using IANA time zone database format (for example, America/New_York). Required if is_vacation_enabled is true.

Response Codes

Code	Description
204 No Content	Successfully updated the broadcaster’s schedule settings.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the broadcaster_id query parameter is not valid. The format of the string in vacation_start_time is not valid. The format of the string in vacation_end_time is not valid. The date in vacation_end_time must be later than the date in vacation_start_time.
401 Unauthorized	The ID in the broadcaster_id query parameter must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the channel:manage:schedule scope. The access token is not valid. The ID in the Client-Id header must match the client ID in the access token.
404 Not Found	The broadcaster's schedule was not found.

Example Request

Schedules the broadcaster’s vacation.

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'

Create Channel Stream Schedule Segment

✎

Adds a single or recurring broadcast to the broadcaster’s streaming schedule. For information about scheduling broadcasts, see Stream Schedule.

Authorization

Requires a user access token that includes the channel:manage:schedule scope.

URL

POST https://api.twitch.tv/helix/schedule/segment

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that owns the schedule to add the broadcast segment to. This ID must match the user ID in the user access token.

Request Body

Field	Type	Required?	Description
start_time	String	Yes	The date and time that the broadcast segment starts. Specify the date and time in RFC3339 format (for example, 2021-07-01T18:00:00Z).
timezone	String	Yes	The time zone where the broadcast takes place. Specify the time zone using IANA time zone database format (for example, America/New_York).
duration	String	Yes	The length of time, in minutes, that the broadcast is scheduled to run. The duration must be in the range 30 through 1380 (23 hours).
is_recurring	Boolean	No	A Boolean value that determines whether the broadcast recurs weekly. Is true if the broadcast recurs weekly. Only partners and affiliates may add non-recurring broadcasts.
category_id	String	No	The ID of the category that best represents the broadcast’s content. To get the category ID, use the Search Categories endpoint.
title	String	No	The broadcast’s title. The title may contain a maximum of 140 characters.

Response Body

Field	Type	Description
data	Object	The broadcaster’s streaming scheduled.
segments	Object[]	A list that contains the single broadcast segment that you added.
id	String	An ID that identifies this broadcast segment.
start_time	String	The UTC date and time (in RFC3339 format) of when the broadcast starts.
end_time	String	The UTC date and time (in RFC3339 format) of when the broadcast ends.
title	String	The broadcast segment’s title.
canceled_until	String	Indicates whether the broadcaster canceled this segment of a recurring broadcast. If the broadcaster canceled this segment, this field is set to the same value that’s in the `end_time` field; otherwise, it’s set to null.
category	Object	The type of content that the broadcaster plans to stream or null if not specified.
id	String	An ID that identifies the category that best represents the content that the broadcaster plans to stream. For example, the game’s ID if the broadcaster will play a game or the Just Chatting ID if the broadcaster will host a talk show.
name	String	The name of the category. For example, the game’s title if the broadcaster will play a game or Just Chatting if the broadcaster will host a talk show.
is_recurring	Boolean	A Boolean value that determines whether the broadcast is part of a recurring series that streams at the same time each week or is a one-time broadcast. Is true if the broadcast is part of a recurring series.
broadcaster_id	String	The ID of the broadcaster that owns the broadcast schedule.
broadcaster_name	String	The broadcaster’s display name.
broadcaster_login	String	The broadcaster’s login name.
vacation	Object	The dates when the broadcaster is on vacation and not streaming. Is set to null if vacation mode is not enabled.
start_time	String	The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation starts.
end_time	String	The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation ends.

Response Codes

Code	Description
200 Ok	Successfully added the broadcast segment.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the broadcaster_id query parameter is not valid. The format of the date and time in the `start_time` field is not valid. The value in the `timezone` field is not valid. The value in the `duration` field is not valid. The ID in the `category_id` field is not valid. The string in the `title` field is too long.
401 Unauthorized	The ID in the broadcaster_id query parameter must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the channel:manage:schedule scope. The access token is not valid. The ID in the Client-Id header must match the client ID in the access token.
403 Forbidden	Only partners and affiliates may add non-recurring broadcast segments.

Example Request

Adds a non-recurring broadcast to the broadcaster’s streaming 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

✎

Updates a scheduled broadcast segment.

For recurring segments, updating a segment’s title, category, duration, and timezone, changes all segments in the recurring schedule, not just the specified segment.

Authorization

Requires a user access token that includes the channel:manage:schedule scope.

URL

PATCH https://api.twitch.tv/helix/schedule/segment

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster who owns the broadcast segment to update. This ID must match the user ID in the user access token.
id	String	Yes	The ID of the broadcast segment to update.

Request Body

Field	Type	Required?	Description
start_time	String	No	The date and time that the broadcast segment starts. Specify the date and time in RFC3339 format (for example, 2022-08-02T06:00:00Z). NOTE: Only partners and affiliates may update a broadcast’s start time and only for non-recurring segments.
duration	String	No	The length of time, in minutes, that the broadcast is scheduled to run. The duration must be in the range 30 through 1380 (23 hours).
category_id	String	No	The ID of the category that best represents the broadcast’s content. To get the category ID, use the Search Categories endpoint.
title	String	No	The broadcast’s title. The title may contain a maximum of 140 characters.
is_canceled	Boolean	No	A Boolean value that indicates whether the broadcast is canceled. Set to true to cancel the segment. NOTE: For recurring segments, the API cancels the first segment after the current UTC date and time and not the specified segment (unless the specified segment is the next segment after the current UTC date and time).
timezone	String	No	The time zone where the broadcast takes place. Specify the time zone using IANA time zone database format (for example, America/New_York).

Response Body

Field	Type	Description
data	Object	The broadcaster’s streaming scheduled.
segments	Object[]	A list that contains the single broadcast segment that you updated.
id	String	An ID that identifies this broadcast segment.
start_time	String	The UTC date and time (in RFC3339 format) of when the broadcast starts.
end_time	String	The UTC date and time (in RFC3339 format) of when the broadcast ends.
title	String	The broadcast segment’s title.
canceled_until	String	Indicates whether the broadcaster canceled this segment of a recurring broadcast. If the broadcaster canceled this segment, this field is set to the same value that’s in the `end_time` field; otherwise, it’s set to null.
category	Object	The type of content that the broadcaster plans to stream or null if not specified.
id	String	An ID that identifies the category that best represents the content that the broadcaster plans to stream. For example, the game’s ID if the broadcaster will play a game or the Just Chatting ID if the broadcaster will host a talk show.
name	String	The name of the category. For example, the game’s title if the broadcaster will play a game or Just Chatting if the broadcaster will host a talk show.
is_recurring	Boolean	A Boolean value that determines whether the broadcast is part of a recurring series that streams at the same time each week or is a one-time broadcast. Is true if the broadcast is part of a recurring series.
broadcaster_id	String	The ID of the broadcaster that owns the broadcast schedule.
broadcaster_name	String	The broadcaster’s display name.
broadcaster_login	String	The broadcaster’s login name.
vacation	Object	The dates when the broadcaster is on vacation and not streaming. Is set to null if vacation mode is not enabled.
start_time	String	The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation starts.
end_time	String	The UTC date and time (in RFC3339 format) of when the broadcaster’s vacation ends.

Response Codes

Code	Description
200 OK	Successfully updated the broadcast segment.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the broadcaster_id query parameter is not valid. The id query parameter is required. The ID in the id query parameter is not valid. The format of the date and time in the `start_time` field is not valid. The value in the `timezone` field is not valid. The value in the `duration` field is not valid. The ID in the `category_id` field is not valid. The string in the `title` field is too long.
401 Unauthorized	The ID in the broadcaster_id query parameter must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the channel:manage:schedule scope. The access token is not valid. The ID in the Client-Id header must match the client ID in the access token.
404 Not Found	The specified broadcast segment was not found.

Example Request

Updates the duration of a non-recurring broadcast segment.

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

✎

Removes a broadcast segment from the broadcaster’s streaming schedule.

NOTE: For recurring segments, removing a segment removes all segments in the recurring schedule.

Authorization

Requires a user access token that includes the channel:manage:schedule scope.

URL

DELETE https://api.twitch.tv/helix/schedule/segment

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that owns the streaming schedule. This ID must match the user ID in the user access token.
id	String	Yes	The ID of the broadcast segment to remove.

Response Codes

Code	Description
204 No Content	Successfully removed the broadcast segment.
400 Bad Request	The broadcaster_id query parameter is required. The ID in the broadcaster_id query parameter is not valid. The id query parameter is required. The ID in the id query parameter is not valid.
401 Unauthorized	The ID in the broadcaster_id query parameter must match the user ID in the user access token. The Authorization header is required and must contain a user access token. The user access token must include the channel:manage:schedule scope. The access token is not valid. The ID in the Client-Id header must match the client ID in the OAuth token.

Example Request

Removes the segment from the broadcaster’s streaming schedule.

curl -X DELETE 'https://api.twitch.tv/helix/schedule/segment?broadcaster_id=141981764&id=eyJzZWdtZW50SUQiOiI4Y2EwN2E2NC0xYTZkLTRjYWItYWE5Ni0xNjIyYzNjYWUzZDkiLCJpc29ZZWFyIjoyMDIxLCJpc29XZWVrIjoyMX0=' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Search Categories

✎

Gets the games or categories that match the specified query.

To match, the category’s name must contain all parts of the query string. For example, if the query string is 42, the response includes any category name that contains 42 in the title. If the query string is a phrase like love computer, the response includes any category name that contains the words love and computer anywhere in the name. The comparison is case insensitive.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/search/categories

Request Query Parameters

Parameter	Type	Required?	Description
query	String	Yes	The URI-encoded search string. For example, encode #archery as `%23archery` and search strings like angel of death as `angel%20of%20death`.
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 items per page. 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 games or categories that match the query. The list is empty if there are no matches.
box_art_url	String	A URL to an image of the game’s box art or streaming category.
name	String	The name of the game or category.
id	String	An ID that uniquely identifies the game or category.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of category names that matched the specified query string.
400 Bad Request	The query query parameter is required.
401 Unauthorized	The Authorization header is required and must contain an app access token or user access token. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets the list of games and categories that contain fort in the name.

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/33214-52x72.jpg"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN"
  }
}

Search Channels

✎

Gets the channels that match the specified query and have streamed content within the past 6 months.

The fields that the API uses for comparison depends on the value that the live_only query parameter is set to. If live_only is false, the API matches on the broadcaster’s login name. However, if live_only is true, the API matches on the broadcaster’s name and category name.

To match, the beginning of the broadcaster’s name or category must match the query string. The comparison is case insensitive. If the query string is angel_of_death, it matches all names that begin with angel_of_death. However, if the query string is a phrase like angel of death, it matches to names starting with angelofdeath or names starting with angel_of_death.

By default, the results include both live and offline channels. To get only live channels set the live_only query parameter to true.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
query	String	Yes	The URI-encoded search string. For example, encode search strings like angel of death as `angel%20of%20death`.
live_only	Boolean	No	A Boolean value that determines whether the response includes only channels that are currently streaming live. Set to true to get only channels that are streaming live; otherwise, false to get live and offline channels. The default is false.
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 items per page. 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 channels that match the query. The list is empty if there are no matches.
broadcaster_language	String	The ISO 639-1 two-letter language code of the language used by the broadcaster. For example, en for English. If the broadcaster uses a language not in the list of supported stream languages, the value is other.
broadcaster_login	String	The broadcaster’s login name.
display_name	String	The broadcaster’s display name.
game_id	String	The ID of the game that the broadcaster is playing or last played.
game_name	String	The name of the game that the broadcaster is playing or last played.
id	String	An ID that uniquely identifies the channel (this is the broadcaster’s ID).
is_live	Boolean	A Boolean value that determines whether the broadcaster is streaming live. Is true if the broadcaster is streaming live; otherwise, false.
tag_ids	String[]	IMPORTANT As of February 28, 2023, this field is deprecated and returns only an empty array. If you use this field, please update your code to use the `tags` field. The list of tags that apply to the stream. The list contains IDs only when the channel is steaming live. For a list of possible tags, see List of All Tags. The list doesn’t include Category Tags.
tags	String[]	The tags applied to the channel.
thumbnail_url	String	A URL to a thumbnail of the broadcaster’s profile image.
title	String	The stream’s title. Is an empty string if the broadcaster didn’t set it.
started_at	String	The UTC date and time (in RFC3339 format) of when the broadcaster started streaming. The string is empty if the broadcaster is not streaming live.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of category names that matched the specified query string.
400 Bad Request	The query query parameter is required.
401 Unauthorized	The Authorization header is required and must contain an app access token or user access token. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets the list of live and offline channels where the broadcaster’s name contains loserfruit.

curl -X GET 'https://api.twitch.tv/helix/search/channels?query=loserfruit' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "broadcaster_language": "en",
      "broadcaster_login": "loserfruit",
      "display_name": "Loserfruit",
      "game_id": "498000",
      "game_name": "House Flipper",
      "id": "41245072",
      "is_live": false,
      "tag_ids": [],
      "tags": [],
      "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=="
  }
}

Example Request

Gets the list of live channels where the broadcaster’s name or category name contains a_seagull.

curl -X GET 'https://api.twitch.tv/helix/search/channels?query=a_seagull&live_only=true' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example 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,
      "tag_ids": [],
      "tags": ["English"],
      "thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/a_seagull-profile_image-4d2d235688c7dc66-300x300.png",
      "title": "a_seagull",
      "started_at": "2020-03-18T17:56:00Z"
    }
  ],
  "pagination": {}
}

Get Stream Key

✎

Gets the channel’s stream key.

Authorization

Requires a user access token that includes the channel:read:stream_key scope.

URL

https://api.twitch.tv/helix/streams/key

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster that owns the channel. The ID must match the user ID in the access token.

Response Body

Field	Type	Description
data	Object[]	A list that contains the channel’s stream key.
stream_key	String	The channel’s stream key.

Response Codes

Code	Decription
200 OK	Successfully retrieved the stream’s key.
400 Bad Request	The broadcaster_id field is required. The ID in the broadcaster_id field is not valid.
401 Unauthorized	The ID in broadcaster_id 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:stream_key scope. The access token is not valid. The client ID specified in the Client-Id header must match the client ID specified in the access token.
403 Forbidden	The user must complete additional steps in order to stream. Present the user with the returned error message.

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 a list of all streams. The list is in descending order by the number of viewers watching the stream. Because viewers come and go during a stream, it’s possible to find duplicate or missing streams in the list as you page through the results.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
user_id	String	No	A user ID used to filter the list of streams. Returns only the streams of those users that are broadcasting. You may specify a maximum of 100 IDs. To specify multiple IDs, include the user_id parameter for each user. For example, `&user_id=1234&user_id=5678`.
user_login	String	No	A user login name used to filter the list of streams. Returns only the streams of those users that are broadcasting. You may specify a maximum of 100 login names. To specify multiple names, include the user_login parameter for each user. For example, `&user_login=foo&user_login=bar`.
game_id	String	No	A game (category) ID used to filter the list of streams. Returns only the streams that are broadcasting the game (category). You may specify a maximum of 100 IDs. To specify multiple IDs, include the game_id parameter for each game. For example, `&game_id=9876&game_id=5432`.
type	String	No	The type of stream to filter the list of streams by. Possible values are: all live The default is all.
language	String	No	A language code used to filter the list of streams. Returns only streams that broadcast in the specified language. Specify the language using an ISO 639-1 two-letter language code or other if the broadcast uses a language not in the list of supported stream languages. You may specify a maximum of 100 language codes. To specify multiple languages, include the language parameter for each language. For example, `&language=de&language=fr`.
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 items per page. The default is 20.
before	String	No	The cursor used to get the previous page of results. The Pagination object in the response contains the cursor’s value. Read More
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 streams.
id	String	An ID that identifies the stream. You can use this ID later to look up the video on demand (VOD).
user_id	String	The ID of the user that’s broadcasting the stream.
user_login	String	The user’s login name.
user_name	String	The user’s display name.
game_id	String	The ID of the category or game being played.
game_name	String	The name of the category or game being played.
type	String	The type of stream. Possible values are: live If an error occurs, this field is set to an empty string.
title	String	The stream’s title. Is an empty string if not set.
tags	String[]	The tags applied to the stream.
viewer_count	Integer	The number of users watching the stream.
started_at	String	The UTC date and time (in RFC3339 format) of when the broadcast began.
language	String	The language that the stream uses. This is an ISO 639-1 two-letter language code or other if the stream uses a language not in the list of supported stream languages.
thumbnail_url	String	A URL to an image of a frame from the last 5 minutes of the stream. Replace the width and height placeholders in the URL (`{width}x{height}`) with the size of the image you want, in pixels.
tag_ids	String[]	IMPORTANT As of February 28, 2023, this field is deprecated and returns only an empty array. If you use this field, please update your code to use the `tags` field. The list of tags that apply to the stream. The list contains IDs only when the channel is steaming live. For a list of possible tags, see List of All Tags. The list doesn’t include Category Tags.
is_mature	Boolean	A Boolean value that indicates whether the stream is meant for mature audiences.
pagination	Object	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. Set the request’s after or before query parameter to this value depending on whether you’re paging forwards or backwards.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of streams.
400 Bad Request	The value in the type query parameter is not valid.
401 Unauthorized	The Authorization header is required and must specify an app access token or user access token. The access token is not valid. The ID in the Client-Id header must match the Client ID in the access token.

Example Request

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

{
  "data": [
    {
      "id": "123456789",
      "user_id": "98765",
      "user_login": "sandysanderman",
      "user_name": "SandySanderman",
      "game_id": "494131",
      "game_name": "Little Nightmares",
      "type": "live",
      "title": "hablamos y le damos a Little Nightmares 1",
      "tags": ["Español"],
      "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": [],
      "is_mature": false
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19"
  }
}

Example Request

Gets streams for the specified logins. If the user is not live, the response doesn’t include them.

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

{
  "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",
      "tags": ["English"],
      "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": [],
      "is_mature": false
    },
    ...
  ],
  "pagination": {}
}

Get Followed Streams

✎

Gets the list of broadcasters that the user follows and that are streaming live.

Authorization

Requires a user access token that includes the user:read:follows scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
user_id	String	Yes	The ID of the user whose list of followed streams you want to get. This ID must match the user ID in the access token.
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 items per page. The default is 100.
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 live streams of broadcasters that the specified user follows. The list is in descending order by the number of viewers watching the stream. Because viewers come and go during a stream, it’s possible to find duplicate or missing streams in the list as you page through the results. The list is empty if none of the followed broadcasters are streaming live.
id	String	An ID that identifies the stream. You can use this ID later to look up the video on demand (VOD).
user_id	String	The ID of the user that’s broadcasting the stream.
user_login	String	The user’s login name.
user_name	String	The user’s display name.
game_id	String	The ID of the category or game being played.
game_name	String	The ID of the category or game being played.
type	String	The type of stream. Possible values are: live If an error occurs, this field is set to an empty string.
title	String	The stream’s title. Is an empty string if not set.
viewer_count	Integer	The number of users watching the stream.
started_at	String	The UTC date and time (in RFC3339 format) of when the broadcast began.
language	String	The language that the stream uses. This is an ISO 639-1 two-letter language code or other if the stream uses a language not in the list of supported stream languages.
thumbnail_url	String	A URL to an image of a frame from the last 5 minutes of the stream. Replace the width and height placeholders in the URL (`{width}x{height}`) with the size of the image you want, in pixels.
tag_ids	String[]	IMPORTANT As of February 28, 2023, this field is deprecated and returns only an empty array. If you use this field, please update your code to use the `tags` field. The list of tags that apply to the stream. The list contains IDs only when the channel is steaming live. For a list of possible tags, see List of All Tags. The list doesn’t include Category Tags.
tags	String[]	The tags applied to the stream.
is_mature	Boolean	A Boolean value that indicates whether the stream is meant for mature audiences.
pagination	Object	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. Set the request’s after query parameter to this value.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of broadcasters that the user follows and that are streaming live.
400 Bad Request	The user_id query parameter is required.
401 Unauthorized	The ID in user_id must match the user ID found in the access token. The Authorization header is required and must contain a user access token. The user access token must include the user:read:follows 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 access token.

Example Request

Gets the streams that the broadcaster 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": [],
      "tags": ["English"]
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19"
  }
}

Create Stream Marker

✎

Adds a marker to a live stream. A marker is an arbitrary point in a live stream that the broadcaster or editor wants to mark, so they can return to that spot later to create video highlights (see Video Producer, Highlights in the Twitch UX).

You may not add markers:

If the stream is not live
If the stream has not enabled video on demand (VOD)
If the stream is a premiere (a live, first-viewing event that combines uploaded videos with live chat)
If the stream is a rerun of a past broadcast, including past premieres.

Authorization

Requires a user access token that includes the channel:manage:broadcast scope.

URL

POST https://api.twitch.tv/helix/streams/markers

Request Body

Field	Type	Required?	Description
user_id	String	Yes	The ID of the broadcaster that’s streaming content. This ID must match the user ID in the access token or the user in the access token must be one of the broadcaster’s editors.
description	String	No	A short description of the marker to help the user remember why they marked the location. The maximum length of the description is 140 characters.

Response Body

Field	Type	Description
data	Object[]	A list that contains the single marker that you added.
id	String	An ID that identifies this marker.
created_at	String	The UTC date and time (in RFC3339 format) of when the user created the marker.
position_seconds	Integer	The relative offset (in seconds) of the marker from the beginning of the stream.
description	String	A description that the user gave the marker to help them remember why they marked the location.

Response Codes

Code	Description
200 OK	Successfully created the marker.
400 Bad Request	The `user_id` field is required. The length of the string in the `description` field is too long.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include the user:manage:broadcast scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in the access token is not authorized to create video markers for the user in the `user_id` field. The user in the access token must own the video or they must be one of the broadcaster's editors.
404 Not Found	The user in the `user_id` field is not streaming live. The ID in the user_id field is not valid. The user hasn't enabled video on demand (VOD).

Example Request

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 from the user’s most recent stream or from the specified VOD/video. A marker is an arbitrary point in a live stream that the broadcaster or editor marked, so they can return to that spot later to create video highlights (see Video Producer, Highlights in the Twitch UX).

Authorization

Requires a user access token that includes the user:read:broadcast or channel:manage:broadcast scope.

URL

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

Request Query Parameter

Parameter	Type	Required?	Description
user_id	String	Yes	A user ID. The request returns the markers from this user’s most recent video. This ID must match the user ID in the access token or the user in the access token must be one of the broadcaster’s editors. This parameter and the video_id query parameter are mutually exclusive.
video_id	String	Yes	A video on demand (VOD)/video ID. The request returns the markers from this VOD/video. The user in the access token must own the video or the user must be one of the broadcaster’s editors. This parameter and the user_id query parameter are mutually exclusive.
first	String	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 items per page. The default is 20.
before	String	No	The cursor used to get the previous page of results. The Pagination object in the response contains the cursor’s value. Read More
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 markers grouped by the user that created the marks.
user_id	String	The ID of the user that created the marker.
user_name	String	The user’s display name.
user_login	String	The user’s login name.
videos	Object[]	A list of videos that contain markers. The list contains a single video.
video_id	String	An ID that identifies this video.
markers	Object[]	The list of markers in this video. The list in ascending order by when the marker was created.
id	String	An ID that identifies this marker.
created_at	String	The UTC date and time (in RFC3339 format) of when the user created the marker.
description	String	The description that the user gave the marker to help them remember why they marked the location. Is an empty string if the user didn’t provide one.
position_seconds	Integer	The relative offset (in seconds) of the marker from the beginning of the stream.
url	String	A URL that opens the video in Twitch Highlighter.
pagination	Object	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. Set the request’s after or before query parameter to this value depending on whether you’re paging forwards or backwards.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of markers.
400 Bad Request	The request must specify either the user_id or video_id query parameter, but not both.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include the user:read:broadcast or user:manage:broadcast scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403 Forbidden	The user in the access token is not authorized to get the video's markers. The user in the access token must own the video or be one of the broadcaster's editors.
404 Not Found	The user specified in the user_id query parameter doesn't have videos.

Example Request

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

Authorization

Requires a user access token that includes the channel:read:subscriptions scope.

A Twitch extensions may use an app access token if the broadcaster has granted the channel:read:subscriptions scope from within the Twitch Extensions manager.

URL

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

Request Query Parameter

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The broadcaster’s ID. This ID must match the user ID in the access token.
user_id	String	No	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.
first	String	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 items per page. The default is 20.
after	String	No	The cursor used to get the next page of results. Do not specify if you set the user_id query parameter. The Pagination object in the response contains the cursor’s value. Read More
before	String	No	The cursor used to get the previous page of results. Do not specify if you set the user_id query parameter. The Pagination object in the response contains the cursor’s value. Read More

Response Body

Field	Type	Description
data	Object[]	The list of users that subscribe to the broadcaster. The list is empty if the broadcaster has no subscribers.
broadcaster_id	String	An ID that identifies the broadcaster.
broadcaster_login	String	The broadcaster’s login name.
broadcaster_name	String	The broadcaster’s display name.
gifter_id	String	The ID of the user that gifted the subscription to the user. Is an empty string if `is_gift` is false.
gifter_login	String	The gifter’s login name. Is an empty string if `is_gift` is false.
gifter_name	String	The gifter’s display name. Is an empty string if `is_gift` is false.
is_gift	Boolean	A Boolean value that determines whether the subscription is a gift subscription. Is true if the subscription was gifted.
plan_name	String	The name of the subscription.
tier	String	The type of subscription. Possible values are: 1000 — Tier 1 2000 — Tier 2 3000 — Tier 3
user_id	String	An ID that identifies the subscribing 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 or previous page of results. Use the cursor to set the request’s after or before query parameter depending on whether you’re paging forwards or backwards.
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).
total	Integer	The total number of users that subscribe to this broadcaster.

Response Codes

Code	Description
200 OK	Successfully retrieved the broadcaster’s list of subscribers.
400 Bad Request	The broadcaster_id query parameter is required.
401 Unauthorized	The ID in broadcaster_id must match the user ID found in the request’s OAuth token. The Authorization header is required and must contain a user access token. The user access token must include the channel:read:subscriptions scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.

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 whether the user subscribes to the broadcaster’s channel.

Authorization

Requires a user access token that includes the user:read:subscriptions scope.

A Twitch extensions may use an app access token if the broadcaster has granted the user:read:subscriptions scope from within the Twitch Extensions manager.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of a partner or affiliate broadcaster.
user_id	String	Yes	The ID of the user that you’re checking to see whether they subscribe to the broadcaster in broadcaster_id. This ID must match the user ID in the access Token.

Response Body

Field	Type	Description
data	Object[]	A list that contains a single object with information about the user’s subscription.
broadcaster_id	String	An ID that identifies the broadcaster.
broadcaster_login	String	The broadcaster’s login name.
broadcaster_name	String	The broadcaster’s display name.
gifter_id	String	The ID of the user that gifted the subscription. 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.
is_gift	Boolean	A Boolean value that determines whether the subscription is a gift subscription. Is true if the subscription was gifted.
tier	String	The type of subscription. Possible values are: 1000 — Tier 1 2000 — Tier 2 3000 — Tier 3

Response Codes

Code	Description
200 OK	The user subscribes to the broadcaster.
400 Bad Request	The broadcaster_id query parameter is required. The user_id query parameter is required.
401 Unauthorized	The ID in user_id must match the user ID found in the request’s OAuth token. The Authorization header is required and must contain a user access token. The user access token must include the user:read:subscriptions scope. The access token is not valid. The client ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found	The user in user_id does not subscribe to the broadcaster in broadcaster_id.

Example Request

Checks whether the user subscribes to the broadcaster’s 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

{
  "data": [
    {
      "broadcaster_id": "149747285",
      "broadcaster_name": "TwitchPresents",
      "broadcaster_login": "twitchpresents",
      "is_gift": false,
      "tier": "1000"
    }
  ]
}

Get All Stream Tags

✎

IMPORTANT Twitch is moving from Twitch-defined tags to channel-defined tags. IMPORTANT As of February 28, 2023, this endpoint returns an empty array. On July 13, 2023, it will return a 410 response.

Gets a list of all stream tags that Twitch defines. The broadcaster may apply any of these to their channel except automatic tags. For an online list of the possible tags, see List of All Tags.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
tag_id	String	No	The ID of the tag to get. Used to filter the list of tags. To specify more than one tag, include the tag_id parameter for each tag to get. For example, `tag_id=1234&tag_id=5678`. The maximum number of IDs you may specify is 100. Ignores invalid IDs but not duplicate IDs.
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 stream tags that the broadcaster can apply to their channel.
tag_id	String	An ID that identifies this 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. Broadcasters may not add automatic tags to their channel. 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>-<country/region>. For example, en-us. 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>-<country/region>. For example, en-us. The value is the localized description.
pagination	Object	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. Set the request’s after query parameter to this value to page forwards through the results.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of tags.
400 Bad Request	The tag_id query parameter is empty (for example, `&tag_id=`). The list of tag IDs is too long.
401 Unauthorized	The Authorization header is required and must specify an app access token or user access token. The access token is not valid. The ID in the Client-Id header must match the Client ID in the access token.

Example Request

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 example that gets the first page of stream tags.
twitch api get /tags/streams

# Twitch CLI example that gets 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

✎

IMPORTANT Twitch is moving from Twitch-defined tags to channel-defined tags. IMPORTANT As of February 28, 2023, this endpoint returns an empty array. On July 13, 2023, it will return a 410 response. If you use this endpoint, please update your code to use Get Channel Information.

Gets the list of stream tags that the broadcaster or Twitch added to their channel.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose stream tags you want to get.

Response Body

Field	Type	Description
data	Object[]	The list of stream tags. The list is empty if the broadcaster or Twitch hasn’t added tags to the broadcaster’s channel.
tag_id	String	An ID that identifies this 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. Broadcasters may not add automatic tags to their channel. 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, en-us. 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, en-us. The value is the localized description.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of tags.
400 Bad Request	The broadcaster_id field is required. The ID in the broadcaster_id field is not valid.
401 Unauthorized	The Authorization header is required and must specify an app access token or user access token. The access token is not valid. The ID in the Client-Id header must match the Client ID in the access token.

Example Request

Gets the TwitchGaming channel’s tags.

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 TwitchGaming channel's tags.
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",
        ...
      }
    }
  ]
}

Get Channel Teams

✎

Gets the list of Twitch teams that the broadcaster is a member of.

Authorization

Requires an app access token or user access token.

URL

GET https://api.twitch.tv/helix/teams/channel

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose teams you want to get.

Response Body

Field	Type	Description
data	Object[]	The list of teams that the broadcaster is a member of. Returns an empty array if the broadcaster is not a member of a team.
broadcaster_id	String	An ID that identifies the broadcaster.
broadcaster_login	String	The broadcaster’s login name.
broadcaster_name	String	The broadcaster’s display name.
background_image_url	String	A URL to the team’s background image.
banner	String	A URL to the team’s banner.
created_at	String	The UTC date and time (in RFC3339 format) of when the team was created.
updated_at	String	The UTC date and time (in RFC3339 format) of the last time the team was updated.
info	String	The team’s description. The description may contain formatting such as Markdown, HTML, newline (\n) characters, etc.
thumbnail_url	String	A URL to a thumbnail image of the team’s logo.
team_name	String	The team’s name.
team_display_name	String	The team’s display name.
id	String	An ID that identifies the team.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of teams.
400 Bad Request	The broadcaster_id query parameter is missing or invalid.
401 Unauthorized	The Authorization header must contain an app access token or user access token. The access token is not valid. The ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found	The broadcaster was not found.

Example Request

Gets a list of Twitch Teams that the specified broadcaster is a member of.

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 about the specified Twitch team. Read More

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
name	String	Yes	The name of the team to get. This parameter and the id parameter are mutually exclusive; you must specify the team’s name or ID but not both.
id	String	Yes	The ID of the team to get. This parameter and the name parameter are mutually exclusive; you must specify the team’s name or ID but not both.

Response Body

Field	Type	Description
data	Object[]	A list that contains the single team that you requested.
users	Object[]	The list of team members.
user_id	String	An ID that identifies the team member.
user_login	String	The team member’s login name.
user_name	String	The team member’s display name.
background_image_url	String	A URL to the team’s background image.
banner	String	A URL to the team’s banner.
created_at	String	The UTC date and time (in RFC3339 format) of when the team was created.
updated_at	String	The UTC date and time (in RFC3339 format) of the last time the team was updated.
info	String	The team’s description. The description may contain formatting such as Markdown, HTML, newline (\n) characters, etc.
thumbnail_url	String	A URL to a thumbnail image of the team’s logo.
team_name	String	The team’s name.
team_display_name	String	The team’s display name.
id	String	An ID that identifies the team.

Response Codes

Code	Description
200 OK	Successfully retrieved the team's information.
400 Bad Request	The name or id query parameter is required. Specify either the name or id query parameter but not both. The ID in the id query parameter is not valid.
401 Unauthorized	The Authorization header must contain an app access token or user access token. The access token is not valid. The ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found	The specified team was not found.

Example Request

Gets information about the specified 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 users.

You may look up users using their user ID, login name, or both but the sum total of the number of users you may look up is 100. For example, you may specify 50 IDs and 50 names or 100 IDs or names, but you cannot specify 100 IDs and 100 names.

If you don’t specify IDs or login names, the request returns information about the user in the access token if you specify a user access token.

To include the user’s verified email address in the response, you must use a user access token that includes the user:read:email scope.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
id	String	No	The ID of the user to get. To specify more than one user, include the id parameter for each user to get. For example, `id=1234&id=5678`. The maximum number of IDs you may specify is 100.
login	String	No	The login name of the user to get. To specify more than one user, include the login parameter for each user to get. For example, `login=foo&login=bar`. The maximum number of login names you may specify is 100.

Response Body

Field	Type	Description
data	Object[]	The list of users.
id	String	An ID that identifies the user.
login	String	The user’s login name.
display_name	String	The user’s display name.
type	String	The type of user. Possible values are: admin — Twitch administrator global_mod staff — Twitch staff "" — Normal user
broadcaster_type	String	The type of broadcaster. Possible values are: affiliate — An affiliate broadcaster affiliate broadcaster partner — A partner broadcaster partner broadcaster "" — A normal broadcaster
description	String	The user’s description of their channel.
profile_image_url	String	A URL to the user’s profile image.
offline_image_url	String	A URL to the user’s offline image.
view_count	Integer	The number of times the user’s channel has been viewed. NOTE: This field has been deprecated (see Get Users API endpoint – “view_count” deprecation). Any data in this field is not valid and should not be used.
email	String	The user’s verified email address. The object includes this field only if the user access token includes the user:read:email scope. If the request contains more than one user, only the user associated with the access token that provided consent will include an email address — the email address for all other users will be empty.
created_at	String	The UTC date and time that the user’s account was created. The timestamp is in RFC3339 format.

Response Codes

Code	Description
200 OK	Successfully retrieved the specified users’ information.
400 Bad Request	The id or login query parameter is required unless the request uses a user access token. The request exceeded the maximum allowed number of id and/or login query parameters.
401 Unauthorized	The Authorization header is required and must contain an app access token or user access token. The access token is not valid. The ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets information about the specified user.

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 specified user’s information. The user ID in the OAuth token identifies the user whose information you want to update.

To include the user’s verified email address in the response, the user access token must also include the user:read:email scope.

Authorization

Requires a user access token that includes the user:edit scope.

URL

PUT https://api.twitch.tv/helix/users

Request Query Parameters

Parameter	Type	Required?	Description
description	string	No	The string to update the channel’s description to. The description is limited to a maximum of 300 characters. To remove the description, specify this parameter but don’t set it’s value (for example, `?description=`).

Response Body

Field	Type	Description
data	Object[]	A list contains the single user that you updated.
id	String	An ID that identifies the user.
login	String	The user's login name.
display_name	String	The user's display name.
type	String	The type of user. Possible values are: admin — Twitch administrator global_mod staff — Twitch staff "" — Normal user
broadcaster_type	String	The type of broadcaster. Possible values are: affiliate — An affiliate broadcaster partner — A partner broadcaster "" — A normal broadcaster
description	String	The user's description of their channel.
profile_image_url	String	A URL to the user's profile image.
offline_image_url	String	A URL to the user's offline image.
view_count	Integer	The number of times the user's channel has been viewed. NOTE: This field has been deprecated (see Get Users API endpoint – "view_count" deprecation). Any data in this field is not valid and should not be used.
email	String	The user's verified email address. The object includes this field only if the user access token includes the user:read:email scope. If the request contains more than one user, only the user associated with the access token that provided consent will include an email address — the email address for all other users will be empty.
created_at	String	The UTC date and time that the user's account was created. The timestamp is in RFC3339 format.

Response Codes

Code	Description
200 OK	Successfully updated the specified user's information.
400 Bad Request	The string in the description query parameter is too long.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include the user:edit scope. The access token is not valid. The ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Updates the description of the specified user.

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 User Block List

✎

Gets the list of users that the broadcaster has blocked. Read More

Authorization

Requires a user access token that includes the user:read:blocked_users scope.

URL

GET https://api.twitch.tv/helix/users/blocks

Request Query Parameters

Parameter	Type	Required?	Description
broadcaster_id	String	Yes	The ID of the broadcaster whose list of blocked users 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 blocked users. The list is in descending order by when the user was blocked.
user_id	String	An ID that identifies the blocked user.
user_login	String	The blocked user’s login name.
display_name	String	The blocked user’s display name.

Response Codes

Code	Description
200 OK	Successfully retrieved the broadcaster's list of blocked users.
400 Bad Request	The broadcaster_id query parameter is required.
401 Unauthorized	The ID in broadcaster_id must match the user ID found in the request’s access token. The Authorization header is required and must contain a user access token. The user access token must include the user:read:blocked_users scope. The access token is not valid. The ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets the specified broadcaster’s list of blocked users.

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 from interacting with or having contact with the broadcaster. The user ID in the OAuth token identifies the broadcaster who is blocking the user.

To learn more about blocking users, see Block Other Users on Twitch.

Authorization

Requires a user access token that includes the user:manage:blocked_users scope.

URL

PUT https://api.twitch.tv/helix/users/blocks

Request Query Parameters

Parameter	Type	Required?	Description
target_user_id	String	Yes	The ID of the user to block. The API ignores the request if the broadcaster has already blocked the user.
source_context	String	No	The location where the harassment took place that is causing the brodcaster to block the user. Possible values are: chat whisper .
reason	String	No	The reason that the broadcaster is blocking the user. Possible values are: harassment spam other

Response Codes

Code	Description
204 No Content	Successfully blocked the user.
400 Bad Request	The target_user_id query parameter is required. The ID in target_user_id cannot be the same as the user ID in the access token. The value in source_context is not valid. The value in reason is not valid.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include the user:manage:blocked_users scope. The access token is not valid. The ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Blocks the specified user.

curl -X PUT 'https://api.twitch.tv/helix/users/blocks?target_user_id=198704263' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \

Unblock User

✎

Removes the user from the broadcaster’s list of blocked users. The user ID in the OAuth token identifies the broadcaster who’s removing the block.

Authorization

Requires a user access token that includes the user:manage:blocked_users scope.

URL

DELETE https://api.twitch.tv/helix/users/blocks

Request Query Parameters

Parameter	Type	Required?	Description
target_user_id	String	Yes	The ID of the user to remove from the broadcaster’s list of blocked users. The API ignores the request if the broadcaster hasn’t blocked the user.

Response Codes

Code	Description
204 No Content	Successfully removed the block.
400 Bad Request	The target_user_id query parameter is required.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include the user:read:blocked_users scope. The access token is not valid. The ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Unblocks the specified user.

curl -X DELETE 'https://api.twitch.tv/helix/users/blocks?target_user_id=198704263' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \

Get User Extensions

✎

Gets a list of all extensions (both active and inactive) that the broadcaster has installed. The user ID in the access token identifies the broadcaster.

Authorization

Requires a user access token that includes the user:read:broadcast or user:edit:broadcast scope. To include inactive extensions, you must include the user:edit:broadcast scope.

URL

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

Response Body

Field	Type	Description
data	Object[]	The list of extensions that the user has installed.
id	String	An ID that identifies the extension.
version	String	The extension's version.
name	String	The extension's name.
can_activate	Boolean	A Boolean value that determines whether the extension is configured and can be activated. Is true if the extension is configured and can be activated.
type	String[]	The extension types that you can activate for this extension. Possible values are: component mobile overlay panel

Response Codes

Code	Description
200 OK	Successfully retrieved the user's installed extensions.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include the user:read:broadcast scope. The access token is not valid. The ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets the extensions that the user has installed.

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 the active extensions that the broadcaster has installed for each configuration.

NOTE: To include extensions that you have under development, you must specify a user access token that includes the user:read:broadcast or user:edit:broadcast scope.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
user_id	String	No	The ID of the broadcaster whose active extensions you want to get. This parameter is required if you specify an app access token and is optional if you specify a user access token. If you specify a user access token and don’t specify this parameter, the API uses the user ID from the access token.

Response Body

Field	Type	Description
data	Object	The active extensions that the broadcaster has installed.
panel	map[string]Object	A dictionary that contains the data for a panel extension. The dictionary’s key is a sequential number beginning with 1. The following fields contain the panel’s data for each key.
active	Boolean	A Boolean value that determines the extension’s activation state. If false, the user has not configured this panel extension.
id	String	An ID that identifies the extension.
version	String	The extension’s version.
name	String	The extension’s name.
overlay	map[string]Object	A dictionary that contains the data for a video-overlay extension. The dictionary’s key is a sequential number beginning with 1. The following fields contain the overlay’s data for each key.
active	Boolean	A Boolean value that determines the extension’s activation state. If false, the user has not configured this overlay extension.
id	String	An ID that identifies the extension.
version	String	The extension’s version.
name	String	The extension’s name.
component	map[string]Object	A dictionary that contains the data for a video-component extension. The dictionary’s key is a sequential number beginning with 1. The following fields contain the component’s data for each key.
active	Boolean	A Boolean value that determines the extension’s activation state. If false, the user has not configured this component extension.
id	String	An ID that identifies the extension.
version	String	The extension’s version.
name	String	The extension’s name.
x	Integer	The x-coordinate where the extension is placed.
y	Integer	The y-coordinate where the extension is placed.

Response Codes

Code	Description
200 OK	Successfully retrieved the user's active extensions.
400 Bad Request	The user_id query parameter is required if you specify an app access token.
401 Unauthorized	The Authorization header is required and must contain an app access token or user access token. The access token is not valid. The ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Gets the user’s active extensions. The API gets the user from the access token.

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 an installed extension’s information. You can update the extension’s activation state, ID, and version number. The user ID in the access token identifies the broadcaster whose extensions you’re updating.

NOTE: If you try to activate an extension under multiple extension types, the last write wins (and there is no guarantee of write order).

Authorization

Requires a user access token that includes the user:edit:broadcast scope.

URL

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

Request Body

Field	Type	Required?	Description
data	map[string]string	Yes	The extensions to update. The `data` field is a dictionary of extension types. The dictionary’s possible keys are: panel, overlay, or component. The key’s value is a dictionary of extensions. For the extension’s dictionary, the key is a sequential number beginning with 1. For panel and overlay extensions, the key’s value is an object that contains the following fields: `active` (true/false), `id` (the extension’s ID), and `version` (the extension’s version). For component extensions, the key’s value includes the above fields plus the `x` and `y` fields, which identify the coordinate where the extension is placed.

Response Body

Field	Type	Description
data	Object	The extensions that the broadcaster updated.
panel	map[string]Object	A dictionary that contains the data for a panel extension. The dictionary’s key is a sequential number beginning with 1. The following fields contain the panel’s data for each key.
active	Boolean	A Boolean value that determines the extension’s activation state. If false, the user has not configured a panel extension.
id	String	An ID that identifies the extension.
version	String	The extension’s version.
name	String	The extension’s name.
overlay	map[string]Object	A dictionary that contains the data for a video-overlay extension. The dictionary’s key is a sequential number beginning with 1. The following fields contain the overlay’s data for each key.
active	Boolean	A Boolean value that determines the extension’s activation state. If false, the user has not configured an overlay extension.
id	String	An ID that identifies the extension.
version	String	The extension’s version.
name	String	The extension’s name.
component	map[string]Object	A dictionary that contains the data for a video-component extension. The dictionary’s key is a sequential number beginning with 1. The following fields contain the component’s data for each key.
active	Boolean	A Boolean value that determines the extension’s activation state. If false, the user has not configured a component extension.
id	String	An ID that identifies the extension.
version	String	The extension’s version.
name	String	The extension’s name.
x	Integer	The x-coordinate where the extension is placed.
y	Integer	The y-coordinate where the extension is placed.

Response Codes

Code	Description
200 OK	Successfully updated the active extensions.
400 Bad Request	The JSON payload is malformed.
401 Unauthorized	The Authorization header is required and must contain a user access token. The user access token must include the user:edit:broadcast scope. The access token is not valid. The ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found	An extension with the specified `id` and `version` values was not found.

Example Request

Updates the the user’s installed extensions.

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 information about one or more published videos. You may get videos by ID, by user, or by game/category.

You may apply several filters to get a subset of the videos. The filters are applied as an AND operation to each video. For example, if language is set to ‘de’ and game_id is set to 21779, the response includes only videos that show playing League of Legends by users that stream in German. The filters apply only if you get videos by user ID or game ID.

Authorization

Requires an app access token or user access token.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
id	String	Yes	A list of IDs that identify the videos you want to get. To get more than one video, include this parameter for each video you want to get. For example, `id=1234&id=5678`. You may specify a maximum of 100 IDs. The endpoint ignores duplicate IDs and IDs that weren't found (if there's at least one valid ID). The id, user_id, and game_id parameters are mutually exclusive.
user_id	String	Yes	The ID of the user whose list of videos you want to get. The id, user_id, and game_id parameters are mutually exclusive.
game_id	String	Yes	A category or game ID. The response contains a maximum of 500 videos that show this content. To get category/game IDs, use the Search Categories endpoint. The id, user_id, and game_id parameters are mutually exclusive.
language	String	No	A filter used to filter the list of videos by the language that the video owner broadcasts in. For example, to get videos that were broadcast in German, set this parameter to the ISO 639-1 two-letter code for German (i.e., DE). For a list of supported languages, see Supported Stream Language. If the language is not supported, use “other.” Specify this parameter only if you specify the game_id query parameter.
period	String	No	A filter used to filter the list of videos by when they were published. For example, videos published in the last week. Possible values are: all day month week The default is "all," which returns videos published in all periods. Specify this parameter only if you specify the game_id or user_id query parameter.
sort	String	No	The order to sort the returned videos in. Possible values are: time — Sort the results in descending order by when they were created (i.e., latest video first). trending — Sort the results in descending order by biggest gains in viewership (i.e., highest trending video first). views — Sort the results in descending order by most views (i.e., highest number of views first). The default is "time." Specify this parameter only if you specify the game_id or user_id query parameter.
type	String	No	A filter used to filter the list of videos by the video's type. Possible case-sensitive values are: all archive — On-demand videos (VODs) of past streams. highlight — Highlight reels of past streams. upload — External videos that the broadcaster uploaded using the Video Producer. The default is "all," which returns all video types. Specify this parameter only if you specify the game_id or user_id query parameter.
first	String	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. Specify this parameter only if you specify the game_id or user_id query parameter.
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 Specify this parameter only if you specify the user_id query parameter.
before	String	No	The cursor used to get the previous page of results. The Pagination object in the response contains the cursor’s value. Read More Specify this parameter only if you specify the user_id query parameter.

Response Body

Fields	Type	Description
data	Object[]	The list of published videos that match the filter criteria.
id	String	An ID that identifies the video.
stream_id	String	The ID of the stream that the video originated from if the video's type is "archive;" otherwise, null.
user_id	String	The ID of the broadcaster that owns the video.
user_login	String	The broadcaster's login name.
user_name	String	The broadcaster's display name.
title	String	The video's title.
description	String	The video's description.
created_at	String	The date and time, in UTC, of when the video was created. The timestamp is in RFC3339 format.
published_at	String	The date and time, in UTC, of when the video was published. The timestamp is in RFC3339 format.
url	String	The video's URL.
thumbnail_url	String	A URL to a thumbnail image of the video. Before using the URL, you must replace the `%{width}` and `%{height}` placeholders with the width and height of the thumbnail you want returned. Due to current limitations, `${width}` must be 320 and `${height}` must be 180.
viewable	String	The video's viewable state. Always set to public.
view_count	Integer	The number of times that users have watched the video.
language	String	The ISO 639-1 two-letter language code that the video was broadcast in. For example, the language code is DE if the video was broadcast in German. For a list of supported languages, see Supported Stream Language. The language value is "other" if the video was broadcast in a language not in the list of supported languages.
type	String	The video's type. Possible values are: archive — An on-demand video (VOD) of one of the broadcaster's past streams. highlight — A highlight reel of one of the broadcaster's past streams. See Creating Highlights. upload — A video that the broadcaster uploaded to their video library. See Upload under Video Producer.
duration	String	The video's length in ISO 8601 duration format. For example, 3m21s represents 3 minutes, 21 seconds.
muted_segments	Object[]	The segments that Twitch Audio Recognition muted; otherwise, null.
duration	Integer	The duration of the muted segment, in seconds.
offset	Integer	The offset, in seconds, from the beginning of the video to where the muted segment begins.
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 or before query parameter depending on whether you're paging forwards or backwards through the results.

Response Codes

Code	Description
200 OK	Successfully retrieved the list of videos.
400 Bad Request	The request must specify either the id or user_id or game_id query parameter. The id, user_id, and game_id query parameters are mutually exclusive; you must specify only one of them. The value in the id query parameter is not valid. The ID in the game_id query parameter is not valid. The value in the type query parameter is not valid. The value in the period query parameter is not valid. The value in the sort query parameter is not valid.
401 Unauthorized	The Authorization header is required and must contain an app access token or user access token. The access token is not valid. The ID specified in the Client-Id header does not match the client ID specified in the access token.
404 Not Found	The ID in the game_id query parameter was not found. The ID in the id query parameter was not found. Returned only if all the IDs were not found; otherwise, the ID is ignored.

Example Request

Gets information about the specified video.

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. You may delete past broadcasts, highlights, or uploads.

Authorization

Requires a user access token that includes the channel:manage:videos scope.

URL

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

Request Query Parameters

Parameter	Type	Required?	Description
id	String	Yes	The list of videos to delete. To specify more than one video, include the id parameter for each video to delete. For example, `id=1234&id=5678`. You can delete a maximum of 5 videos per request. Ignores invalid video IDs. If the user doesn’t have permission to delete one of the videos in the list, none of the videos are deleted.

Response Body

Fields	Type	Description
data	String[]	The list of IDs of the videos that were deleted.

Response Codes

Code	Description
200 OK	Successfully deleted the list of videos.
400 Bad Request	The id query parameter is required. The request exceeded the number of allowed id query parameters.
401 Unauthorized	The caller is not authorized to delete the specified video. The Authorization header is required and must contain a user access token. The user access token must include the channel:manage:videos scope. The access token is not valid. The ID specified in the Client-Id header does not match the client ID specified in the access token.

Example Request

Deletes the two specified videos.

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

✎

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.

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. This ID must match the user ID in the user access token.
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 Codes

Code	Description
204 No Content	Successfully sent the whisper message or the message was silently dropped.
400 Bad Request	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	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 must include the user:manage:whispers scope. The access 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 access token.
403 Forbidden	Suspended users may not send whisper messages. 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"}'