Contents

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

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

CodeDescription
200 OKSuccessfully 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

NameTypeRequired?Description
extension_idStringNoThe 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.
typeStringNoThe type of analytics report to get. Possible values are:
  • overview_v2
started_atStringNoThe 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_atStringNoThe 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.
firstIntegerNoThe 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.
afterStringNoThe 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

CodeDescription
200 OKSuccessfully 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:
  • 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

CodeDescription
200 OKSuccessfully 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

CodeDescription
200 OKSuccessfully retrieved the broadcaster's list of followers.
400 Bad RequestPossible reasons:
  • The user_id query parameter is required.
  • The broadcaster_id query parameter is not valid.
  • The user_id query parameter is required.
401 UnauthorizedPossible 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 CodeDescription
200 OKSuccessfully updated the custom reward.
400 Bad Request
  • 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

FieldTypeDescription
dataObject[]The list of emotes that the specified broadcaster created. If the broadcaster hasn't created custom emotes, the list is empty.
   idStringAn ID that identifies this emote.
   nameStringThe name of the emote. This is the name that viewers type in the chat window to get the emote to appear.
   imagesObjectThe 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_1xStringA URL to the small version (28px x 28px) of the emote.
      url_2xStringA URL to the medium version (56px x 56px) of the emote.
      url_4xStringA URL to the large version (112px x 112px) of the emote.
   tierStringThe 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_typeStringThe 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_idStringAn ID that identifies the emote set that the emote belongs to.
   formatString[]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.
   scaleString[]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_modeString[]The background themes that the emote is available in. Possible themes are:
  • dark
  • light
templateStringA 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

CodeDescription
200 OKSuccessfully 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

FieldTypeDescription
dataObject[]The list of global emotes.
   idStringAn ID that identifies this emote.
   nameStringThe name of the emote. This is the name that viewers type in the chat window to get the emote to appear.
   imagesObjectThe 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_1xStringA URL to the small version (28px x 28px) of the emote.
      url_2xStringA URL to the medium version (56px x 56px) of the emote.
      url_4xStringA URL to the large version (112px x 112px) of the emote.
   formatString[]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.
   scaleString[]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_modeString[]The background themes that the emote is available in. Possible themes are:
  • dark
  • light
templateStringA 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

CodeDescription
200 OKSuccessfully 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
    }
  ]
}

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

CodeDescription
204 No ContentSuccessfully 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

CodeDescription
200 OKSuccessfully 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 ForbiddenThe sender is not permitted to send chat messages to the broadcaster’s chat room.
422 Unprocessable EntityThe 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

ParameterTypeRequired?Description
user_idStringYesThe ID of the user whose chat color you want to update. This ID must match the user ID in the access token.
colorStringYesThe 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

CodeDescription
204 No ContentSuccessfully 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

CodeDescription
200 OKSuccessfully 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

CodeMeaning
200 OKConduit updated.
400 Bad Request
  • Invalid shard count
  • The id query parameter is required.
401 UnauthenticatedAuthorization 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

CodeMeaning
204 No ContentSuccessfully deleted the conduit.
400 Bad RequestThe id query parameter is required.
401 UnauthenticatedAuthorization 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

ParameterTypeDescription
dataObject[]List of information about a conduit's shards.
   idStringShard ID.
   statusStringThe 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.
   transportObjectThe transport details used to send the notifications.
      methodStringThe transport method. Possible values are:
  • webhook
  • websocket
      callbackStringThe callback URL where the notifications are sent. Included only if method is set to webhook.
      session_idStringAn ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket.
      connected_atStringThe UTC date and time that the WebSocket connection was established. Included only if method is set to websocket.
      disconnected_atStringThe UTC date and time that the WebSocket connection was lost. Included only if method is set to websocket.
paginationObjectContains information used to page through a list of results. The object is empty if there are no more pages left to page through.
   cursorStringThe cursor used to get the next page of results. Use the cursor to set the request’s after query parameter.

Response Codes

CodeMeaning
200 OKSuccessfully retrieved shards.
400 Bad RequestThe id query parameter is required.
401 UnauthenticatedAuthorization 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?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

ParameterTypeRequiredDescription
conduit_idStringYesConduit ID.
shardsObject[]YesList of shards to update.
   idStringYesShard ID.
   transportObjectYesThe transport details that you want Twitch to use when sending you notifications.
      methodStringNoThe transport method. Possible values are:
  • webhook
  • websocket
      callbackStringNoThe 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.
      secretStringNoThe 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_idStringNoAn 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

ParameterTypeDescription
dataObject[]List of successful shard updates.
   idStringShard ID.
   statusStringThe 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.
   transportObjectThe transport details used to send the notifications.
      methodStringThe transport method. Possible values are:
  • webhook
  • websocket
      callbackStringThe callback URL where the notifications are sent. Included only if method is set to webhook.
      session_idStringAn ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket.
      connected_atStringThe UTC date and time that the WebSocket connection was established. Included only if method is set to websocket.
      disconnected_atStringThe UTC date and time that the WebSocket connection was lost. Included only if method is set to websocket.
errorsObject[]List of unsuccessful updates.
   idStringShard ID.
   messageStringThe 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.
   codeStringError codes used to represent a specific error condition while attempting to update shards.

Response Codes

CodeMeaning
202 AcceptedSuccessfully retrieved shards.
400 Bad RequestThe id query parameter is required.
401 UnauthenticatedAuthorization 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": "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

ParameterTypeRequired?Description
skuStringYesThe 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.
costObjectYesAn object that contains the product's cost information.
   amountIntegerYesThe product's price.
   typeStringYesThe type of currency. Possible values are:
  • bits — The minimum price is 1 and the maximum is 10000.
display_nameStringYesThe product's name as displayed in the extension. The maximum length is 255 characters.
in_developmentBooleanNoA 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.
expirationStringNoThe 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_broadcastBooleanNoA 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

FieldTypeDescription
dataObject[]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.
   skuStringThe product's SKU. The SKU is unique across an extension's products.
   costObjectAn object that contains the product's cost information.
      amountIntegerThe product's price.
      typeStringThe type of currency. Possible values are:
  • bits
   in_developmentBooleanA Boolean value that indicates whether the product is in development. If true, the product is not available for public use.
   display_nameStringThe product's name as displayed in the extension.
   expirationStringThe date and time, in RFC3339 format, when the product expires.
   is_broadcastBooleanA 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

CodeDescription
200 OKSuccessfully 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

ParameterTypeRequiredDescription
typeStringYesThe 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.
versionStringYesThe version number that identifies the definition of the subscription type that you want the response to use.
conditionObjectYesA 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.
transportObjectYesThe transport details that you want Twitch to use when sending you notifications.
   methodStringYesThe transport method. Possible values are:
  • webhook
  • websocket
  • conduit
   callbackStringNo

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.

   secretStringNoThe 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_idStringNoAn 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_idStringNoAn 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

ParameterTypeDescription
dataObject[]A list that contains the single subscription that you created.
   idStringAn ID that identifies the subscription.
   statusStringThe 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).
   typeStringThe subscription’s type. See Subscription Types.
   versionStringThe version number that identifies this definition of the subscription’s data.
   conditionObjectThe subscription’s parameter values. This is a string-encoded JSON object whose contents are determined by the subscription type.
   created_atStringThe date and time (in RFC3339 format) of when the subscription was created.
   transportObjectThe transport details used to send the notifications.
      methodStringThe transport method. Possible values are:
  • webhook
  • websocket
  • conduit
      callbackStringThe callback URL where the notifications are sent. Included only if method is set to webhook.
      session_idStringAn ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket.
      connected_atStringThe UTC date and time that the WebSocket connection was established. Included only if method is set to websocket.
      conduit_idStringAn ID that identifies the conduit to send notifications to. Included only if method is set to conduit.
   costIntegerThe amount that the subscription counts against your limit. Learn More
totalIntegerThe total number of subscriptions you’ve created.
total_costIntegerThe sum of all of your subscription costs. Learn More
max_total_costIntegerThe maximum total cost that you’re allowed to incur for all subscriptions you create.

Response Codes

CodeMeaning
202 AcceptedSuccessfully 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 ForbiddenThe access token is missing the required scopes.
409 ConflictA 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 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.

ParameterTypeRequired?Description
statusStringNoFilter 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.
  • 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.
typeStringNoFilter subscriptions by subscription type. For a list of subscription types, see Subscription Types.
user_idStringNoFilter 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.
afterStringNoThe cursor used to get the next page of results. The pagination object in the response contains the cursor's value.

Response Body

FieldTypeDescription
dataObject[]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.
   idStringAn ID that identifies the subscription.
   statusStringThe 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.
   typeStringThe subscription's type. See Subscription Types.
   versionStringThe version number that identifies this definition of the subscription's data.
   conditionObjectThe subscription's parameter values. This is a string-encoded JSON object whose contents are determined by the subscription type.
   created_atStringThe date and time (in RFC3339 format) of when the subscription was created.
   transportObjectThe transport details used to send the notifications.
      methodStringThe transport method. Possible values are:
  • webhook
  • websocket
      callbackStringThe callback URL where the notifications are sent. Included only if method is set to webhook.
      session_idStringAn ID that identifies the WebSocket that notifications are sent to. Included only if method is set to websocket.
      connected_atStringThe UTC date and time that the WebSocket connection was established. Included only if method is set to websocket.
      disconnected_atStringThe UTC date and time that the WebSocket connection was lost. Included only if method is set to websocket.
   costIntegerThe amount that the subscription counts against your limit. Learn More
totalIntegerThe total number of subscriptions that you've created.
total_costIntegerThe sum of all of your subscription costs. Learn More
max_total_costIntegerThe maximum total cost that you're allowed to incur for all subscriptions that you create.
paginationObjectAn 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.
   cursorStringThe cursor value that you set the after query parameter to.

Response Codes

CodeDescription
200 OKSuccessfully 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"
    }
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN"
  }
}

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

CodeDescription
200 OKSuccessfully 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=9876' \
-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 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

CodeDescription
200 OKSuccessfully 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

CodeDescription
204 No ContentSuccessfully 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"
    }
  ]
}

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'