Contents

Twitch API Reference

Resource Endpoint Description
Ads Start Commercial

Starts a commercial on a specified channel.

Analytics Get Extension Analytics

Gets a URL that Extension developers can use to download analytics reports (CSV files) for their Extensions. The URL is valid for 5 minutes. For details about analytics and the fields returned, see the Insights & Analytics guide.

Analytics Get Game Analytics

Gets a URL that game developers can use to download analytics reports (CSV files) for their games. The URL is valid for 5 minutes.

Bits Get Bits Leaderboard

Gets a ranked list of Bits leaderboard information for an authorized broadcaster.

Bits Get Cheermotes

Retrieves the list of available Cheermotes, animated emotes to which viewers can assign Bits, to cheer in chat. Cheermotes returned are available throughout Twitch, in all Bits-enabled channels.

Bits Get Extension Transactions

Get Extension Transactions allows extension back end servers to fetch a list of transactions that have occurred for their extension across all of Twitch.

Channels Get Channel Information

Gets channel information for users.

Channels Modify Channel Information

Modifies channel information for users.

Channels Get Channel Editors

Gets a list of users who have editor permissions for a specific channel.

Channel Points Create Custom Rewards

Creates a Custom Reward on a channel.

 

Channel Points Delete Custom Reward

Deletes a Custom Reward on a channel.

Channel Points Get Custom Reward

Returns a list of Custom Reward objects for the Custom Rewards on a channel. 

Channel Points Get Custom Reward Redemption

Returns Custom Reward Redemption objects for a Custom Reward on a channel that was created by the same client_id

Channel Points Update Custom Reward

Updates a Custom Reward created on a channel. 

 

Channel Points Update Redemption Status

Updates the status of Custom Reward Redemption objects on a channel that are in the UNFULFILLED status.

 

Clips Create Clip

Creates a clip programmatically. This returns both an ID and an edit URL for the new clip.

Clips Get Clips

Gets clip information by clip ID (one or more), broadcaster ID (one only), or game ID (one only).

Entitlements Get Code Status

Gets the status of one or more provided codes. This API requires that the caller is an authenticated Twitch user. The API is throttled to one request per second per authenticated user.

Entitlements Get Drops Entitlements

Gets a list of entitlements for a given organization that have been granted to a game, user, or both.

Entitlements Redeem Code

Redeems one or more provided codes to the authenticated Twitch user. This API requires that the caller is an authenticated Twitch user. This API requires that the caller is an authenticated Twitch user. The API is throttled to one request per second per authenticated user.

EventSub Create EventSub Subscription

Creates an EventSub subscription.

EventSub Delete EventSub Subscription

Delete an EventSub subscription.

EventSub Get EventSub Subscriptions

Get a list of your EventSub subscriptions. The subscriptions are paginated and ordered by most recent first.

Games Get Top Games

Gets games sorted by number of current viewers on Twitch, most popular first.

Games Get Games

Gets game information by game ID or name.

Hype Train Get Hype Train Events

Gets the information of the most recent Hype Train of the given channel ID.

Moderation Check AutoMod Status

Determines whether a string message meets the channel’s AutoMod requirements.

Moderation Manage Held AutoMod Messages

Allow or deny a message that was held for review by AutoMod.

Moderation Get Banned Events

Returns all user bans and un-bans in a channel.

Moderation Get Banned Users

Returns all banned and timed-out users in a channel.

Moderation Get Moderators

Returns all moderators in a channel.

Moderation Get Moderator Events

Returns a list of moderators or users added and removed as moderators from a channel.

Polls Get Polls

NEW Get information about all polls or specific polls for a Twitch channel. Poll information is available for 90 days.

Polls Create Poll

NEW Create a poll for a specific Twitch channel.

Polls End Poll

NEW End a poll that is currently active.

Predictions Get Predictions

NEW Get information about all Channel Points Predictions or specific Channel Points Predictions for a Twitch channel.

Predictions Create Prediction

NEW Create a Channel Points Prediction for a specific Twitch channel.

Predictions End Prediction

NEW Lock, resolve, or cancel a Channel Points Prediction.

Search Search Categories

Returns a list of games or categories that match the query via name either entirely or partially.

Search Search Channels

Returns a list of channels that match the query via channel name or description either entirely or partially.

Streams Get Stream Key

Gets the channel stream key for a user.

Streams Get Streams

Gets information about active streams. Streams are returned sorted by number of current viewers, in descending order.

Streams Get Followed Streams

Gets information about active streams belonging to channels that the authenticated user follows.

Streams Create Stream Marker

Creates a marker in the stream of a user specified by user ID. A marker is an arbitrary point in a stream that the broadcaster wants to mark.

Streams Get Stream Markers

Gets a list of markers for either a specified user’s most recent stream or a specified VOD/video (stream), ordered by recency. A marker is an arbitrary point in a stream that the broadcaster wants to mark.

Subscriptions Get Broadcaster Subscriptions

Gets all of a broadcaster’s subscriptions.

Subscriptions Check User Subscription

Checks if a specific user is subscribed to a specific channel.

Tags Get All Stream Tags

Gets the list of all stream tags defined by Twitch, optionally filtered by tag ID(s).

Tags Get Stream Tags

Gets the list of current stream tags that have been set for a channel.

Tags Replace Stream Tags

Applies specified tags to a specified stream, overwriting any existing tags applied to that stream.

Teams Get Channel Teams

Retrieves a list of Twitch Teams of which the specified channel/broadcaster is a member.

Teams Get Teams

Gets information for a specific Twitch Team.

Users Get Users

Gets information about one or more specified Twitch users. Users are identified by optional user IDs and/or login name.

Users Update User

Updates the description of a user specified by a Bearer token.

Users Get Users Follows

Gets information on follow relationships between two Twitch users. Information returned is sorted in order, most recent follow first.

Users Create User Follows

Adds a specified user to the followers of a specified channel.

Users Delete User Follows

Deletes a specified user from the followers of a specified channel.

Users Get User Block List

Gets a specified user’s block list. The list is sorted by when the block occurred in descending order (i.e. most recent block first).

Users Block User

Blocks the specified user on behalf of the authenticated user.

Users Unblock User

Unblocks the specified user on behalf of the authenticated user.

Users Get User Extensions

Gets a list of all extensions (both active and inactive) for a specified user, identified by a Bearer token.

Users Get User Active Extensions

Gets information about active extensions installed by a specified user, identified by a user ID or Bearer token.

Users Update User Extensions

Updates the activation state, extension ID, and/or version number of installed extensions for a specified user, identified by a Bearer token.

Videos Get Videos

Gets video information by video ID (one or more), user ID (one only), or game ID (one only).

Videos Delete Videos

Deletes one or more videos. Videos are past broadcasts, Highlights, or uploads.

Webhooks Get Webhook Subscriptions

Gets the Webhook subscriptions of an application identified by a Bearer token, in order of expiration.

Start Commercial

Starts a commercial on a specified channel.

Authentication

  • OAuth Token required
  • Required scope: channel:edit:commercial

Pagination Support

None

URL

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

Required Query Parameter

None

Required Body Parameter

Parameter Type Description
broadcaster_id string ID of the channel requesting a commercial
Minimum: 1 Maximum: 1
length integer Desired length of the commercial in seconds. 
Valid options are 30, 60, 90, 120, 150, 180.

Optional Query Parameters

None

Response Fields

Parameter Type Description
length integer Length of the triggered commercial
message string Provides contextual information on why the request failed
retry_after integer Seconds until the next commercial can be served on this channel

 

Example Request

This request starts a commercial.

curl -X POST 'https://api.twitch.tv/helix/channels/commercial' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
--data-raw '{
  "broadcaster_id": "41245072",
  "length": 60
}'

Example Response

{
  "data": [{
    "length" : 60,
    "message" : "",
    "retry_after" : 480
  }]
}

 

Get Extension Analytics

Gets a URL that Extension developers can use to download analytics reports (CSV files) for their Extensions. The URL is valid for 5 minutes.

If you specify a future date, the response will be “Report Not Found For Date Range.” If you leave both started_at and ended_at blank, the API returns the most recent date of data.

Authentication

  • OAuth token required
  • Required scope: analytics:read:extensions

URL

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

Required Query Parameters

None

Optional Query Parameters

Name Type Description
after string Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries without extension_id. If an extension_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query.
ended_at string Ending date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z. The report covers the entire ending date; e.g., if 2018-05-01T00:00:00Z is specified, the report covers up to 2018-05-01T23:59:59Z.

If this is provided, started_at also must be specified. If ended_at is later than the default end date, the default date is used. Default: 1-2 days before the request was issued (depending on report availability).
extension_id string Client ID value assigned to the extension when it is created. If this is specified, the returned URL points to an analytics report for just the specified extension. If this is not specified, the response includes multiple URLs (paginated), pointing to separate analytics reports for each of the authenticated user’s Extensions.
first integer Maximum number of objects to return. Maximum: 100. Default: 20.
started_at string Starting date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z. This must be on or after January 31, 2018.

If this is provided, ended_at also must be specified. If started_at is earlier than the default start date, the default date is used.  The file contains one row of data per day.
type string Type of analytics report that is returned. Currently, this field has no affect on the response as there is only one report type. If additional types were added, using this field would return only the URL for the specified report. Limit: 1. Valid values: "overview_v2".

Response Fields

FieldTypeDescription
ended_atstringReport end date/time.
extension_idstringID of the extension whose analytics data is being provided.
paginationobject containing a stringA cursor value, to be used in a subsequent request to specify the starting point of the next set of results. This is returned only if extension_id is not specified in the request.
started_atstringReport start date/time. Note this may differ from (be later than) the started_at value in the request; the response value is the date when data for the extension is available.
typestringType of report.
URLstringURL to the downloadable CSV file containing analytics data. Valid for 5 minutes.

Example Request #1

This gets the URLs for all reports for all Extensions of the authenticated client. For the purpose of this example, assume the request is issued on June 1, 2018.

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

Example Response #1

{
   "data": [
      {
         "extension_id": "efgh",
         "URL": "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/dynamic/LoL%20ADC_overview_v2_2018-03-01_2018-06-01_8a879932-8e70-7a4c-2b97-e0eaba28c3b0.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAI7LOPgTrAIVYE6KQ%2F20180731%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180731T202847Z&X-Amz-Expires=60&X-Amz-Security-Token=FQoDYXdzEDMaDObdwyOVISdo6feHSSK3A9R9gMFeS5frG5Dsr4k4tJemqCIazhsQJrpsehBoOufaQkCxrb8RD3oU0xC5pWrZe9kN%2BnezIoLOgTtFRAqTzdIr7J5iUOxGFyKN9XmrmUHGexFfALvoPQWUJNbxoFU6shajSmO3sPK2GnuEaGmIrAqjKrim8saLHDV%2FdSi2ZH3fFx6sBQEGv13Lx0zua7AsvaL%2BSfhIAcOazWjYLMU5N9bxXmaN7IAIF4UjNPqbg07RMWW70hm0edH0RPi%2Fw00faeeSvmreHq6c1C1Lu8a7AysMb0pEGBT7VxmuGmWsXyjLWZ6oNgbx88HXoMJpmAn5Y1hUu7VzOaa84T%2BmCF5Sbn7hbB1xIiPdzaVQ%2Bd85sy4ln09h7dgKh6GFE1VTas2v7RJU1lyD%2FZ%2FWKBwV5Ol8GEGrF1pme8mSBpPGUAJ4vxjLmrGL7ctty%2F0vXke3PyD%2B4%2FtHZ67xaw0y8EKrau23Xvt3blkcDNoQYOfcS%2FqbaK%2BHpyVq4bIBtQq%2BHYU5MuFkgEuwSe5zPDle1ysKSN11B6B6Sy7Httrq542OONS%2BfURkczMbKSPEShddN32Y9VUqKYdUo%2FsWVQQoy7uC2wU%3D&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3Bfilename%3D%22WoW%20Armory_overview_v1_2018-04-30_2018-06-01.csv%22&X-Amz-Signature=eb7721e40cbfd1d7409887dae3792cdb2add025ace953a63ba8e3545b92ae058",
         "type": "overview_v2",
         "date_range": {
            "started_at": "2018-03-01T00:00:00Z",
            "ended_at": "2018-06-01T00:00:00Z"
         }
      },
      ...
   ],
   "pagination": {"cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6NX19"}
}

Get Game Analytics

Gets a URL that game developers can use to download analytics reports (CSV files) for their games. The URL is valid for 5 minutes. For detail about analytics and the fields returned, see the Insights & Analytics guide.

The response has a JSON payload with a data field containing an array of games information elements and can contain a pagination field containing information required to query for more streams.

If you specify a future date, the response will be “Report Not Found For Date Range.” If you leave both started_at and ended_at blank, the API returns the most recent date of data.

Authentication

  • OAuth token required
  • Required scope: analytics:read:games

URL

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

Required Query Parameters

None

Optional Query Parameters

Name Type Description
after string Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries without game_id. If a game_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query.
ended_at string Ending date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z. The report covers the entire ending date; e.g., if 2018-05-01T00:00:00Z is specified, the report covers up to 2018-05-01T23:59:59Z.

If this is provided, started_at also must be specified. If ended_at is later than the default end date, the default date is used. Default: 1-2 days before the request was issued (depending on report availability).
first integer Maximum number of objects to return. Maximum: 100. Default: 20.
game_id string Game ID. If this is specified, the returned URL points to an analytics report for just the specified game. If this is not specified, the response includes multiple URLs (paginated), pointing to separate analytics reports for each of the authenticated user’s games.
started_at string Starting date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z.

If this is provided, ended_at also must be specified. If started_at is earlier than the default start date, the default date is used. Default: 365 days before the report was issued. The file contains one row of data per day.
type string Type of analytics report that is returned. Currently, this field has no affect on the response as there is only one report type. If additional types were added, using this field would return only the URL for the specified report. Limit: 1. Valid values: "overview_v2".

Response Fields

Field Type Description
ended_at string Report end date/time.
game_id string ID of the game whose analytics data is being provided.
pagination Object containing a string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. This is returned only if game_id is not specified in the request.
started_at string Report start date/time.
type string Type of report.
URL string URL to the downloadable CSV file containing analytics data. Valid for 5 minutes.

Example Request #1

This gets the URL for a downloadable CSV report for game ID 493057, covering the period January 1, 2018 to March 1, 2018.

curl -X GET 'https://api.twitch.tv/helix/analytics/games?game_id=493057&started_at=2018-01-01T00:00:00Z&ended_at=2018-03-01T00:00:00Z' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response #1

{
  "data": [
    {
      "game_id" : "493057",
      "URL" : "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/games/66170/overview/1518307200000.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAJP7WFIAF26K7BC2Q%2F20180222%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180222T220651Z&X-Amz-Expires=60&X-Amz-Security-Token=FQoDYXdzEE0aDLKNl9aCgfuikMKI%2ByK3A4e%2FR%2B4to%2BmRZFUuslNKs%2FOxKeySB%2BAU87PBtNGCxQaQuN2Q8KI4Vg%2Bve2x5eenZdoH0ZM7uviM94sf2GlbE9Z0%2FoJRmNGNhlU3Ua%2FupzvByCoMdefrU8Ziiz4j8EJCgg0M1j2aF9f8bTC%2BRYwcpP0kjaZooJS6RFY1TTkh659KBA%2By%2BICdpVK0fxOlrQ%2FfZ6vIYVFzvywBM05EGWX%2F3flCIW%2BuZ9ZxMAvxcY4C77cOLQ0OvY5g%2F7tuuGSO6nvm9Eb8MeMEzSYPr4emr3zIjxx%2Fu0li9wjcF4qKvdmnyk2Bnd2mepX5z%2BVejtIGBzfpk%2Fe%2FMqpMrcONynKoL6BNxxDL4ITo5yvVzs1x7OumONHcsvrTQsd6aGNQ0E3lrWxcujBAmXmx8n7Qnk4pZnHZLgcBQam1fIGba65Gf5Ern71TwfRUsolxnyIXyHsKhd2jSmXSju8jH3iohjv99a2vGaxSg8SBCrQZ06Bi0pr%2FTiSC52U1g%2BlhXYttdJB4GUdOvaxR8n6PwMS7HuAtDJUui8GKWK%2F9t4OON3qhF2cBt%2BnV%2BDg8bDMZkQ%2FAt5blvIlg6rrlCu0cYko4ojb281AU%3D&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3Bfilename%3DWarframe-overview-2018-02-11.csv&X-Amz-Signature=49cc07cbd9d753b00315b66f49b9e4788570062ff3bd956288ab4f164cf96708",
      "type" : "overview_v2",
      "date_range" : {
        "started_at" : "2018-01-01T00:00:00Z",
        "ended_at" : "2018-03-01T00:00:00Z"
      }
    }
  ]
}

Example Request #2

This gets the first 5 URLs (paginated) for all reports for all games of the authenticated client. The request is issued on June 14, 2018.

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

Example Response #2

{
  "data": [
    {
      "game_id": "9821",
      "URL": "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/games/9821/overview/1526428800000.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAJQ4MLJCNPIYDOZ4Q%2F20180517%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180517T231129Z&X-Amz-Expires=60&X-Amz-Security-Token=FQoDYXdzEK7%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDD0JCM06UswayN4iVyK3AzIiwI0Qf4KRs2yk9nCiocQOwmMWa7FPJnJEd%2FIxljnmZy%2BphQEEWN3%2Bt8k06wZysfPHvW71zcrIeclv11kNtXaYojC%2FHVKJWO8EnicIQE73kokr16fkf1Q4eglQBuu56jJQoTsEn2UkgZff9XHx69LyFvLYf33ue10CjeJE1bY65%2B6LtcPKciJK%2FNRS1TyUsz%2FiQjyxMEUpAKm39HxNtNKFM5xehjAoWC1KfJc52XVQGFO%2Fm2EQiJj6RoifNkiIQKb4m7nGr86zvIQKDQcxcpVbiGNEcC8UugZgCnuspSPjuJLARb%2BNT%2FjLKopd2%2FUKDlIY%2BAoyEk%2B%2FGIWL5TgvjjmT5uaJ5AcnTm4b7DlV%2FkmDsYHFQez0Mu4%2BwoujZEqR0K%2BtDSyAvva2nUUGabZuDeaaiQD4JfrokXC5GWtninHQCAoPiC4q%2FMYkHS82wxPjJp0l4cStwzEDQ5LJ4cehKm4tCoY1m1whWIJsNuyfLtIUH2rBTuF9D5DFmsmpXiKc4LE9saQgSlLwNBEGASqAbRuy7Tc2ZlcIp1lBllioxhoYL3XcjaXOX3qluWGMwgXdV2Odq0L03MkoxuL31wU%3D&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3Bfilename%3D%22Heroes%20of%20Might%20and%20Magic%20IV-overview_v1-2018-05-16.csv%22&X-Amz-Signature=47af9a041970244b51fa6dd6a31d78ae9ff56a4db76a54d3e1b8a7ec4631defa",
      "type" : "overview_v2",
      "date_range" : {
        "started_at" : "2018-03-13T00:00:00Z",
        "ended_at" : "2018-06-13T00:00:00Z"
      }
    },
    ...
  ],
  "pagination": {"cursor": "eyJiIjpudWxsLJxhIjoiIn0gf5"}
}

Get Bits Leaderboard

Gets a ranked list of Bits leaderboard information for an authorized broadcaster.

Authentication

  • OAuth token required
  • Required scope: bits:read

URL

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

Required Query Parameters

None

Optional Query Parameters

NameTypeDescription
countintegerNumber of results to be returned. Maximum: 100. Default: 10.
periodstringTime period over which data is aggregated (PST time zone). This parameter interacts with started_at. Valid values follow. Default: "all".
  • "day" – 00:00:00 on the day specified in started_at, through 00:00:00 on the following day.
  • "week" – 00:00:00 on Monday of the week specified in started_at, through 00:00:00 on the following Monday.
  • "month" – 00:00:00 on the first day of the month specified in started_at, through 00:00:00 on the first day of the following month.
  • "year" – 00:00:00 on the first day of the year specified in started_at, through 00:00:00 on the first day of the following year.
  • "all" – The lifetime of the broadcaster's channel. If this is specified (or used by default), started_at is ignored.
started_atstringTimestamp for the period over which the returned data is aggregated. Must be in RFC 3339 format. If this is not provided, data is aggregated over the current period; e.g., the current day/week/month/year. This value is ignored if period is "all".

Any + operator should be URL encoded.

Currently, the HH:MM:SS part of this value is used only to identify a given day in PST and otherwise ignored. For example, if the started_at value resolves to 5PM PST yesterday and period is "day", data is returned for all of yesterday.
user_idstringID of the user whose results are returned; i.e., the person who paid for the Bits.

As long as count is greater than 1, the returned data includes additional users, with Bits amounts above and below the user specified by user_id.

If user_id is not provided, the endpoint returns the Bits leaderboard data across top users (subject to the value of count).

Response Fields

Field Type Description
ended_at string End of the date range for the returned data.
rank integer Leaderboard rank of the user.
score integer Leaderboard score (number of Bits) of the user.
started_at string Start of the date range for the returned data.
total integer Total number of results (users) returned. This is count or the total number of entries in the leaderboard, whichever is less.
user_id string ID of the user (viewer) in the leaderboard entry.
user_login string User login name.
user_name string Display name corresponding to user_id.

Example Request

This gets information about the top two Bits leaderboard entries for the user specified by Bearer token cfabdegwdoklmawdzdo98xt2fo512y. Information is returned for the current week.

curl -X GET 'https://api.twitch.tv/helix/bits/leaderboard?count=2&period=week' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "user_id": "158010205",
      "user_login": "tundracowboy",
      "user_name": "TundraCowboy",
      "rank": 1,
      "score": 12543
    },
    {
      "user_id": "7168163",
      "user_login": "topramens",
      "user_name": "Topramens",
      "rank": 2,
      "score": 6900
    }
  ],
  "date_range": {
    "started_at": "2018-02-05T08:00:00Z",
    "ended_at": "2018-02-12T08:00:00Z"
  },
  "total": 2
}

Get Cheermotes

Retrieves the list of available Cheermotes, animated emotes to which viewers can assign Bits, to cheer in chat. Cheermotes returned are available throughout Twitch, in all Bits-enabled channels.

URL

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

Authentication

OAuth or App Access Token required.

Optional Query Parameter

Parameter Type Description
broadcaster_id string ID for the broadcaster who might own specialized Cheermotes.

Response Fields

Parameter Type Description
prefix string The string used to Cheer that precedes the Bits amount.
tiers array An array of Cheermotes with their metadata.
min_bits integer Minimum number of bits needed to be used to hit the given tier of emote.  
id  string ID of the emote tier. Possible tiers are: 1,100,500,1000,5000, 10k, or 100k.
color string Hex code for the color associated with the bits of that tier. Grey, Purple, Teal, Blue, or Red color to match the base bit type.
images object Structure containing both animated and static image sets, sorted by light and dark.
can_cheer Boolean Indicates whether or not emote information is accessible to users.
show_in_bits_card Boolean Indicates whether or not we hide the emote from the bits card.
type string Shows whether the emote is global_first_party,  global_third_party, channel_custom, display_only, or sponsored.
order integer Order of the emotes as shown in the bits card, in ascending order.
last_updated string The data when this Cheermote was last updated.
is_charitable Boolean Indicates whether or not this emote provides a charity contribution match during charity campaigns.

Example Requests

This request lists all global Cheermotes.

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

This request lists all global Cheermotes and any Cheermote uploaded by this broadcaster.

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

Example Response

{
  "data": [
    {
      "prefix": "Cheer",
      "tiers": [
        {
          "min_bits": 1,
          "id": "1",
          "color": "#979797",
          "images": {
            "dark": {
              "animated": {
                "1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/1.gif",
                "1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/1.5.gif",
                "2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/2.gif",
                "3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/3.gif",
                "4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/1/4.gif"
              },
              "static": {
                "1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/1.png",
                "1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/1.5.png",
                "2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/2.png",
                "3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/3.png",
                "4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/static/1/4.png"
              }
            },
            "light": {
              "animated": {
                "1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/1.gif",
                "1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/1.5.gif",
                "2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/2.gif",
                "3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/3.gif",
                "4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/animated/1/4.gif"
              },
              "static": {
                "1": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/1.png",
                "1.5": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/1.5.png",
                "2": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/2.png",
                "3": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/3.png",
                "4": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/light/static/1/4.png"
              }
            }
          },
          "can_cheer": true,
          "show_in_bits_card": true
        }
        ...
      ],
      "type": "global_first_party",
      "order": 1,
      "last_updated": "2018-05-22T00:06:04Z",
      "is_charitable": false
    },
    ...
  ]
}

Get Extension Transactions

Get Extension Transactions allows extension back end servers to fetch a list of transactions that have occurred for their extension across all of Twitch. A transaction is a record of a user exchanging Bits for an in-Extension digital good.

URL

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

Description

Gets the list of Extension Transactions for a given extension.

Authentication

OAuth or App Access Token required.

Query Parameters

Parameter Required Type Description
extension_id Yes string ID of the extension to list transactions for. Maximum: 1
id No string Transaction IDs to look up. Can include multiple to fetch multiple transactions in a single request.

Format: Repeated Query Parameter, eg. /helix/extensions/transactions?extension_id=1234&id=1&id=2&id=3

Maximum: 100
after No string The cursor used to fetch the next page of data. This only applies to queries without ID. If an ID is specified, it supersedes the cursor.
first No integer Maximum number of objects to return.

Maximum: 100
Default: 20

Return Values

Parameter Type Description
pagination object containing a string If provided, is the key used to fetch the next page of data. If not provided, the current response is the last page of data available.
data array Array of requested transactions.
id string Unique identifier of the Bits in Extensions Transaction.
timestamp string UTC timestamp when this transaction occurred.
broadcaster_id string Twitch User ID of the channel the transaction occurred on.
broadcaster_login string Login name of the broadcaster.
broadcaster_name string Twitch Display Name of the broadcaster.
user_id string Twitch User ID of the user who generated the transaction.
user_login string Login name of the user who generated the transaction.
user_name string Twitch Display Name of the user who generated the transaction.
product_type string Enum of the product type. Currently only BITS_IN_EXTENSION.
product_data object JSON Object representing the product acquired, as it looked at the time of the transaction.
domain string Set this field to twitch.ext + your extension ID.
broadcast Boolean Flag that denotes whether or not the data was sent over the extension pubsub to all instances of the extension.
expiration string Always empty since only unexpired products can be purchased.
sku string Unique identifier for the product across the extension.
cost object JSON Object representing the cost to acquire the product.
amount integer Number of Bits required to acquire the product.
type` enum Always the string
“Bits”.    
displayName string Display Name of the product.
inDevelopment Boolean Flag used to indicate if the product is in development. Either true or false.

 

Example Request

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

Example Response

{
     "data": [
          {
               "id": "74c52265-e214-48a6-91b9-23b6014e8041",
               "timestamp": "2019-01-28T04:15:53.325Z",
               "broadcaster_id": "439964613",
               "broadcaster_login": "chikuseuma",
               "broadcaster_name": "chikuseuma",
               "user_id": "424596340",
               "user_login": "quotrok",
               "user_name": "quotrok",
               "product_type": "BITS_IN_EXTENSION",
               "product_data": {
                     "sku": "testSku100",
                     "cost": {
                          "amount": 100,
                          "type": "bits"
                     },
                     "displayName": "Test Sku",
                     "inDevelopment": false
                }
           },
           {
                "id": "8d303dc6-a460-4945-9f48-59c31d6735cb",
                "timestamp": "2019-01-18T09:10:13.397Z",
                "broadcaster_id": "439964613",
                "broadcaster_login": "chikuseuma",
                "broadcaster_name": "chikuseuma"
                "user_id": "439966926",
                "user_login": "liscuit",
                "user_name": "liscuit",
                "product_type": "BITS_IN_EXTENSION",
                "product_data": {
                     "sku": "testSku100",
                     "cost": {
                          "amount": 100,
                          "type": "bits"
                     },
                     "displayName": "Test Sku",
                     "inDevelopment": false
                }
          },
          ...
     ],
     "pagination": {
          "cursor": "cursorString"
     }
}

 

Get Channel Information

Gets channel information for users.

Authentication

Valid user token or app access token.

URL

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

Required Query Parameters

Parameter Type Description
broadcaster_id string ID of the channel to be updated

Optional Query Parameters

None

Return Values

Parameter Type Description
broadcaster_id string Twitch User ID of this channel owner
broadcaster_name string Twitch user display name of this channel owner
game_name string Name of the game being played on the channel
game_id string Current game ID being played on the channel
broadcaster_language string Language of the channel. A language value is either the ISO 639-1 two-letter code for a supported stream language or “other”.
title string Title of the stream
delay integer Stream delay in seconds

Response Codes

HTTP Code Meaning
200 Channel/Stream returned successfully
400 Missing Query Parameter
500 Internal Server Error; Failed to get channel information

Example Request

This request gets information about the TwitchDev channel.

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

Example Response

{
  "data": [
    {
      "broadcaster_id": "141981764",
      "broadcaster_login": "twitchdev",
      "broadcaster_name": "TwitchDev",
      "broadcaster_language": "en",
      "game_id": "509670",
      "game_name": "Science & Technology",
      "title": "TwitchDev Monthly Update // May 6, 2021",
      "delay": 0
    }
  ]
}

Modify Channel Information

Modifies channel information for users.

Authentication

  • OAuth Token required

  • Required scope: channel:manage:broadcast

URL

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

Required Query Parameters

Parameter Type Description
broadcaster_id string ID of the channel to be updated

Body Parameters

All parameters are optional, but at least one parameter must be provided.

Parameter Type Description
game_id string The current game ID being played on the channel. Use “0” or “” (an empty string) to unset the game.
broadcaster_language string The language of the channel. A language value must be either the ISO 639-1 two-letter code for a supported stream language or “other”.
title string The title of the stream. Value must not be an empty string.
delay integer Stream delay in seconds. Stream delay is a Twitch Partner feature; trying to set this value for other account types will return a 400 error.

Response Codes

HTTP Code Meaning
204 Channel/Stream updated successfully
400 Missing or invalid parameter
500 Internal server error; failed to update channel

 

Example Request

curl -X PATCH 'https://api.twitch.tv/helix/channels?broadcaster_id=41245072' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
--data-raw '{"game_id":"33214", "title":"there are helicopters in the game? REASON TO PLAY FORTNITE found", "broadcaster_language":"en"}'

Example Response

204 No Content

 

Get Channel Editors

Gets a list of users who have editor permissions for a specific channel.

Authentication

  • OAuth user token required
  • Required scope: channel:read:editors

URL

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

Required Query Parameters

Parameter Type Description
broadcaster_id string Broadcaster’s user ID associated with the channel.

Optional Query Parameters

None.

Response Fields

Field Type Description
user_id string User ID of the editor.
user_name string Display name of the editor.
created_at string Date and time the editor was given editor permissions.

Response Codes

Code Meaning
200 A list of channel editors is returned.
400 Query parameter is missing.
401 Authorization is missing or there was an OAuth token mismatch.

Example Request

This example gets a list of editors for the TwitchDev channel which has a User ID of 141981764.

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

Example Response

{
  "data": [
    {
      "user_id": "182891647",
      "user_name": "mauerbac",
      "created_at": "2019-02-15T21:19:50.380833Z"
    },
    {
      "user_id": "135093069",
      "user_name": "BlueLava",
      "created_at": "2018-03-07T16:28:29.872937Z"
    }
  ]
}

Create Custom Rewards

Creates a Custom Reward on a channel.

Authentication

Query parameter broadcaster_id must match the user_id in the User-Access token

Authorization

Requires OAuth Scope: channel:manage:redemptions

URL

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

Pagination

None.

Required Query Parameter

Parameter Type Description
broadcaster_id string Provided broadcaster_id must match the user_id in the auth token.

Body Values

Parameter Required Type Description
title Yes string The title of the reward
prompt No string The prompt for the viewer when they are redeeming the reward
cost Yes integer The cost of the reward
is_enabled No Boolean Is the reward currently enabled, if false the reward won’t show up to viewers. Defaults true
background_color No string Custom background color for the reward. Format: Hex with # prefix. Example: #00E5CB.
is_user_input_required No Boolean Does the user need to enter information when redeeming the reward. Defaults false
is_max_per_stream_enabled No Boolean Whether a maximum per stream is enabled. Defaults to false.
max_per_stream No integer The maximum number per stream if enabled
is_max_per_user_per_stream_enabled No Boolean Whether a maximum per user per stream is enabled. Defaults to false.
max_per_user_per_stream No integer The maximum number per user per stream if enabled
is_global_cooldown_enabled No Boolean Whether a cooldown is enabled. Defaults to false.
global_cooldown_seconds No integer The cooldown in seconds if enabled
should_redemptions_skip_request_queue No Boolean Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status. Defaults false

Return Values

Parameter Type Description
broadcaster_id string ID of the channel the reward is for
broadcaster_login string Broadcaster’s user login name.
broadcaster_name string Display name of the channel the reward is for
id string ID of the reward
title string The title of the reward
prompt string The prompt for the viewer when they are redeeming the reward
cost integer The cost of the reward
image object Set of custom images of 1x, 2x and 4x sizes for the reward { url_1x: string, url_2x: string, url_4x: string }, can be null if no images have been uploaded
default_image object Set of default images of 1x, 2x and 4x sizes for the reward { url_1x: string, url_2x: string, url_4x: string }
background_color string Custom background color for the reward. Format: Hex with # prefix. Example: #00E5CB.
is_enabled Boolean Is the reward currently enabled, if false the reward won’t show up to viewers
is_user_input_required Boolean Does the user need to enter information when redeeming the reward
max_per_stream_setting object Whether a maximum per stream is enabled and what the maximum is. { is_enabled: bool, max_per_stream: int }
max_per_user_per_stream_setting object Whether a maximum per user per stream is enabled and what the maximum is. { is_enabled: bool, max_per_user_per_stream: int }
global_cooldown_setting object Whether a cooldown is enabled and what the cooldown is. { is_enabled: bool, global_cooldown_seconds: int }
is_paused Boolean Is the reward currently paused, if true viewers can’t redeem
is_in_stock Boolean Is the reward currently in stock, if false viewers can’t redeem
should_redemptions_skip_request_queue Boolean Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status.
redemptions_redeemed_current_stream integer The number of redemptions redeemed during the current live stream. Counts against the max_per_stream_setting limit. Null if the broadcasters stream isn’t live or max_per_stream_setting isn’t enabled.
cooldown_expires_at string Timestamp of the cooldown expiration. Null if the reward isn’t on cooldown.

Response Codes

HTTP Code Meaning
200 OK: A list of the Custom Rewards is returned
400 Bad Request: Query Parameter missing or invalid
401 Unauthenticated: Missing/invalid Token
403 Forbidden: Channel Points are not available for the broadcaster
500 Internal Server Error: Something bad happened on our side

Example Request

This request creates a custom reward:


curl -X POST 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
    "title":"game analysis 1v1",
    "cost":50000
}'

Example Response

 {
     "data": [
         {
             "broadcaster_name": "torpedo09",
             "broadcaster_login": "torpedo09",
             "broadcaster_id": "274637212",
             "id": "afaa7e34-6b17-49f0-a19a-d1e76eaaf673",
             "image": null,
             "background_color": "#00E5CB",
             "is_enabled": true,
             "cost": 50000,
             "title": "game analysis 1v1",
             "prompt": "",
             "is_user_input_required": false,
             "max_per_stream_setting": {
                 "is_enabled": false,
                 "max_per_stream": 0
             },
             "max_per_user_per_stream_setting": {
                 "is_enabled": false,
                 "max_per_user_per_stream": 0
             },
             "global_cooldown_setting": {
                 "is_enabled": false,
                 "global_cooldown_seconds": 0
             },
             "is_paused": false,
             "is_in_stock": true,
             "default_image": {
                 "url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
                 "url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
                 "url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
             },
             "should_redemptions_skip_request_queue": false,
             "redemptions_redeemed_current_stream": null,
             "cooldown_expires_at": null
         }
     ]
 }

Delete Custom Reward

Deletes a Custom Reward on a channel.

Only rewards created programmatically by the same client_id can be deleted. Any UNFULFILLED Custom Reward Redemptions of the deleted Custom Reward will be updated to the FULFILLED status.

Authentication

Query parameter broadcaster_id must match the user_id in the User Access token

Authorization

Required OAuth Scope: channel:manage:redemptions

The Custom Reward specified by id must have been created by the client_id attached to the access token.

URL

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

Pagination

None.

Required Query Parameters

Parameter Type Description
broadcaster_id string Provided broadcaster_id must match the user_id in the auth token
id string ID of the Custom Reward to delete, must match a Custom Reward on broadcaster_id’s channel.

Response Codes

HTTP Code Meaning
204 No Content
400 Bad Request: Query/Body Parameter missing or invalid
401 Unauthenticated: Missing/invalid Token
403 Forbidden: The Custom Reward was created by a different client_id or Channel Points are not available for the broadcaster
404 Not Found: The Custom Reward doesn’t exist with the id and broadcaster_id specified
500 Internal Server Error: Something bad happened on our side

Example Request 

This request deletes a custom reward:

curl -X DELETE 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=b045196d-9ce7-4a27-a9b9-279ed341ab28' \
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'

Example Response 

204 No Content

Get Custom Reward

Returns a list of Custom Reward objects for the Custom Rewards on a channel. Developers only have access to update and delete rewards that were created programmatically by the same/calling client_id.

Authentication

Query parameter broadcaster_id must match the user_id in the User Access token

Authorization

Requires OAuth Scope: channel:read:redemptions

URL

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

Pagination

None.

There is a limit of 50 Custom Rewards on a channel at a time. This includes both enabled and disabled Custom Rewards.

Required Query Parameters

Parameter Type Description
broadcaster_id string Provided broadcaster_id must match the user_id in the auth token

Optional Query Parameters

Parameter Type Description
id string When used, this parameter filters the results and only returns reward objects for the Custom Rewards with matching ID. Maximum: 50
only_manageable_rewards Boolean When set to true, only returns custom rewards that the calling client_id can manage. Defaults false.

Return Values

Parameter Type Description
broadcaster_id string ID of the channel the reward is for
broadcaster_login string Login of the channel the reward is for
broadcaster_name string Display name of the channel the reward is for
id string ID of the reward
title string The title of the reward
prompt string The prompt for the viewer when they are redeeming the reward
cost integer The cost of the reward
image object Set of custom images of 1x, 2x and 4x sizes for the reward { url_1x: string, url_2x: string, url_4x: string }, can be null if no images have been uploaded
default_image object Set of default images of 1x, 2x and 4x sizes for the reward { url_1x: string, url_2x: string, url_4x: string }
background_color string Custom background color for the reward. Format: Hex with # prefix. Example: #00E5CB.
is_enabled Boolean Is the reward currently enabled, if false the reward won’t show up to viewers
is_user_input_required Boolean Does the user need to enter information when redeeming the reward
max_per_stream_setting object Whether a maximum per stream is enabled and what the maximum is. { is_enabled: bool, max_per_stream: int }
max_per_user_per_stream_setting object Whether a maximum per user per stream is enabled and what the maximum is. { is_enabled: bool, max_per_user_per_stream: int }
global_cooldown_setting object Whether a cooldown is enabled and what the cooldown is. { is_enabled: bool, global_cooldown_seconds: int }
is_paused Boolean Is the reward currently paused, if true viewers can’t redeem
is_in_stock Boolean Is the reward currently in stock, if false viewers can’t redeem
should_redemptions_skip_request_queue Boolean Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status.
redemptions_redeemed_current_stream integer The number of redemptions redeemed during the current live stream. Counts against the max_per_stream_setting limit. Null if the broadcasters stream isn’t live or max_per_stream_setting isn’t enabled.
cooldown_expires_at string Timestamp of the cooldown expiration. Null if the reward isn’t on cooldown.

Response Codes

HTTP Code Meaning
200 OK: A list of the Custom Rewards is returned
400 Bad Request: Query Parameter missing or invalid
401 Unauthenticated: Missing/invalid Token
403 Forbidden: Channel Points are not available for the broadcaster
404 Not Found: No Custom Rewards with the specified IDs were found
500 Internal Server Error: Something bad happened on our side

Example Request #1

This request lists custom rewards:

curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212'
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'

Example Response #1

{
     "data": [
         {
             "broadcaster_name": "torpedo09",
             "broadcaster_login": "torpedo09",
             "broadcaster_id": "274637212",
             "id": "92af127c-7326-4483-a52b-b0da0be61c01",
             "image": null,
             "background_color": "#00E5CB",
             "is_enabled": true,
             "cost": 50000,
             "title": "game analysis",
             "prompt": "",
             "is_user_input_required": false,
             "max_per_stream_setting": {
                 "is_enabled": false,
                 "max_per_stream": 0
             },
             "max_per_user_per_stream_setting": {
                 "is_enabled": false,
                 "max_per_user_per_stream": 0
             },
             "global_cooldown_setting": {
                 "is_enabled": false,
                 "global_cooldown_seconds": 0
             },
             "is_paused": false,
             "is_in_stock": true,
             "default_image": {
                 "url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
                 "url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
                 "url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
             },
             "should_redemptions_skip_request_queue": false,
             "redemptions_redeemed_current_stream": null,
             "cooldown_expires_at": null
         }
     ]
 }

Example Request #2

This request lists custom rewards that the calling Client ID can manage:

curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&only_manageable_rewards=true'
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'​​​​​​​

Example Response #2

{
     "data": [
         {
             "broadcaster_name": "torpedo09",
             "broadcaster_id": "274637212",
             "id": "92af127c-7326-4483-a52b-b0da0be61c01",
             "image": null,
             "background_color": "#00E5CB",
             "is_enabled": true,
             "cost": 50000,
             "title": "game analysis",
             "prompt": "",
             "is_user_input_required": false,
             "max_per_stream_setting": {
                 "is_enabled": false,
                 "max_per_stream": 0
             },
             "max_per_user_per_stream_setting": {
                 "is_enabled": false,
                 "max_per_user_per_stream": 0
             },
             "global_cooldown_setting": {
                 "is_enabled": false,
                 "global_cooldown_seconds": 0
             },
             "is_paused": false,
             "is_in_stock": true,
             "default_image": {
                 "url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
                 "url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
                 "url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
             },
             "should_redemptions_skip_request_queue": false,
             "redemptions_redeemed_current_stream": null,
             "cooldown_expires_at": null
         }
     ]
 }

Example Request #3

This request bulk-gets custom rewards.

curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01'
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'​​​​​​​​​​​​​​

Example Response #3

{
     "data": [
         {
             "broadcaster_name": "torpedo09",
             "broadcaster_id": "274637212",
             "id": "92af127c-7326-4483-a52b-b0da0be61c01",
             "image": null,
             "background_color": "#00E5CB",
             "is_enabled": true,
             "cost": 50000,
             "title": "game analysis",
             "prompt": "",
             "is_user_input_required": false,
             "max_per_stream_setting": {
                 "is_enabled": false,
                 "max_per_stream": 0
             },
             "max_per_user_per_stream_setting": {
                 "is_enabled": false,
                 "max_per_user_per_stream": 0
             },
             "global_cooldown_setting": {
                 "is_enabled": false,
                 "global_cooldown_seconds": 0
             },
             "is_paused": false,
             "is_in_stock": true,
             "default_image": {
                 "url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
                 "url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
                 "url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
             },
             "should_redemptions_skip_request_queue": false,
             "redemptions_redeemed_current_stream": null,
             "cooldown_expires_at": null
         }
     ]
 }

Get Custom Reward Redemption

Returns Custom Reward Redemption objects for a Custom Reward on a channel that was created by the same client_id.

Developers only have access to get and update redemptions for the rewards created programmatically by the same client_id.

Authentication

Query parameter broadcaster_id must match the user_id in the User Access token

Authorization

Requires OAuth Scope: channel:read:redemptions

URL

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

Pagination

Maximum of 50 per page. Returns oldest first.

Required Query Parameters

Parameter Type Description
broadcaster_id string Provided broadcaster_id must match the user_id in the auth token
reward_id string When ID is not provided, this parameter returns paginated Custom Reward Redemption objects for redemptions of the Custom Reward with ID reward_id

Optional Query Parameters

Parameter Type Description
id string When used, this param filters the results and only returns Custom Reward Redemption objects for the redemptions with matching ID. Maximum: 50
status string When id is not provided, this param is required and filters the paginated Custom Reward Redemption objects for redemptions with the matching status. Can be one of UNFULFILLED, FULFILLED or CANCELED
sort string Sort order of redemptions returned when getting the paginated Custom Reward Redemption objects for a reward. One of: OLDEST, NEWEST. Default: OLDEST.
after string Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries without ID. If an ID is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query.
first integer Number of results to be returned when getting the paginated Custom Reward Redemption objects for a reward. Limit: 50. Default: 20.

Return Values

Parameter Type Description
broadcaster_id string The id of the broadcaster that the reward belongs to.
broadcaster_login string Broadcaster’s user login name.
broadcaster_name string The display name of the broadcaster that the reward belongs to.
id string The ID of the redemption.
user_login string The login of the user who redeemed the reward.
user_id string The ID of the user that redeemed the reward.
user_name string The display name of the user that redeemed the reward.
reward object Basic information about the Custom Reward that was redeemed at the time it was redeemed. { “id”: string, “title”: string, “prompt”: string, “cost”: int, }
user_input string The user input provided. Empty string if not provided.
status string One of UNFULFILLED, FULFILLED or CANCELED
redeemed_at string RFC3339 timestamp of when the reward was redeemed.

Response Codes

HTTP Code Meaning
200 Ok: A list of the Custom Reward Redemptions is returned
400 Bad Request: Query Parameter missing or invalid
401 Unauthenticated: Missing/invalid Token
403 Forbidden: The Custom Reward was created by a different client_id or Channel Points are not available for the broadcaster
404 Not Found: No Custom Reward Redemptions with the specified ids were found
500 Internal Server Error: Something bad happened on our side

Example Request #1

This example lists custom reward redemptions for a specific reward:

curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=274637212&reward_id=92af127c-7326-4483-a52b-b0da0be61c01&status=CANCELED' \
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'

Example Response #1

 {
    "data": [
          {
            "broadcaster_name": "torpedo09",
            "broadcaster_login": "torpedo09",
            "broadcaster_id": "274637212",
            "id": "17fa2df1-ad76-4804-bfa5-a40ef63efe63",
            "user_login": "torpedo09",
            "user_id": "274637212",
            "user_name": "torpedo09",
            "user_input": "",
            "status": "CANCELED",
            "redeemed_at": "2020-07-01T18:37:32Z",
            "reward": {
                "id": "92af127c-7326-4483-a52b-b0da0be61c01",
                "title": "game analysis",
                "prompt": "",
                "cost": 50000
                  }
        }
    ],
    "pagination": {
        "cursor":      "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6Ik1UZG1ZVEprWmpFdFlXUTNOaTAwT0RBMExXSm1ZVFV0WVRRd1pXWTJNMlZtWlRZelgxOHlNREl3TFRBM0xUQXhWREU0T2pNM09qTXlMakl6TXpFeU56RTFOMW89In19"
    }
}

Example Request #2

This example gets custom reward redemptions by ID.

curl -X GET 'https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=274637212&reward_id=92af127c-7326-4483-a52b-b0da0be61c01&id=17fa2df1-ad76-4804-bfa5-a40ef63efe63' \
-H 'Client-Id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2'

Example Response #2

{
    "data": [
              {
            "broadcaster_name": "torpedo09",
            "broadcaster_login": "torpedo09",
            "broadcaster_id": "274637212",
            "id": "17fa2df1-ad76-4804-bfa5-a40ef63efe63",
            "user_id": "274637212",
            "user_name": "torpedo09",
            "user_input": "",
            "status": "CANCELED",
            "redeemed_at": "2020-07-01T18:37:32Z",
            "reward": {
                "id": "92af127c-7326-4483-a52b-b0da0be61c01",
                "title": "game analysis",
                "prompt": "",
                "cost": 50000
            }
        }
    ]
}

Update Custom Reward

Updates a Custom Reward created on a channel.

Only rewards created programmatically by the same client_id can be updated.

Authentication

Query parameter broadcaster_id must match the user_id in the User Access token

Authorization

Requires OAuth Scope: channel:manage:redemptions

The Custom Reward specified by id must have been created by the client_id attached to the access token.

URL

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

Pagination

None.

Required Query Parameters

ParameterTypeDescription
broadcaster_idstringProvided broadcaster_id must match the user_id in the auth token.
idstringID of the Custom Reward to update, must match a Custom Reward on broadcaster_id’s channel.

Body Values

Parameter Required Type Description
title No string The title of the reward
prompt No string The prompt for the viewer when they are redeeming the reward
cost No integer The cost of the reward
background_color No string Custom background color for the reward. Format: Hex with # prefix. Example: #00E5CB.
is_enabled No Boolean Is the reward currently enabled, if false the reward won’t show up to viewers
is_user_input_required No Boolean Does the user need to enter information when redeeming the reward.
is_max_per_stream_enabled No Boolean Whether a maximum per stream is enabled
max_per_stream No integer The maximum number per stream if enabled
is_max_per_user_per_stream_enabled No Boolean Whether a maximum per user per stream is enabled. Defaults to false.
max_per_user_per_stream No integer The maximum number per user per stream if enabled
is_global_cooldown_enabled No Boolean Whether a cooldown is enabled. Defaults to false.
global_cooldown_seconds No integer The cooldown in seconds if enabled
is_paused No Boolean Is the reward currently paused, if true viewers can’t redeem
should_redemptions_skip_request_queue No Boolean Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status.

Return Values

Parameter Type Description
broadcaster_id string ID of the channel the reward is for
broadcaster_login string Broadcaster’s user login name.
broadcaster_name string Display name of the channel the reward is for
id string ID of the reward
title string The title of the reward
prompt string The prompt for the viewer when they are redeeming the reward
cost integer The cost of the reward
image object Set of custom images of 1x, 2x and 4x sizes for the reward { url_1x: string, url_2x: string, url_4x: string }, can be null if no images have been uploaded
default_image object Set of default images of 1x, 2x and 4x sizes for the reward { url_1x: string, url_2x: string, url_4x: string }
background_color string Custom background color for the reward. Format: Hex with # prefix. Example: #00E5CB.
is_enabled Boolean Is the reward currently enabled, if false the reward won’t show up to viewers
is_user_input_required Boolean Does the user need to enter information when redeeming the reward
max_per_stream_setting object Whether a maximum per stream is enabled and what the maximum is. { is_enabled: bool, max_per_stream: int }
max_per_user_per_stream_setting object Whether a maximum per user per stream is enabled and what the maximum is. { is_enabled: bool, max_per_user_per_stream: int }
global_cooldown_setting object Whether a cooldown is enabled and what the cooldown is. { is_enabled: bool, global_cooldown_seconds: int }
is_paused Boolean Is the reward currently paused, if true viewers can’t redeem
is_in_stock Boolean Is the reward currently in stock, if false viewers can’t redeem
should_redemptions_skip_request_queue Boolean Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status.
redemptions_redeemed_current_stream integer The number of redemptions redeemed during the current live stream. Counts against the max_per_stream_setting limit. Null if the broadcasters stream isn’t live or max_per_stream_setting isn’t enabled.
cooldown_expires_at string Timestamp of the cooldown expiration. Null if the reward isn’t on cooldown

Response Codes

HTTP Code Meaning
200 OK: A list of the Custom Rewards is returned
400 Bad Request: Query Parameter missing or invalid
401 Unauthenticated: Missing/invalid Token
403 Forbidden: The Custom Reward was created by a different client_id or Channel Points are not available for the broadcaster
404 Not Found: The Custom Reward doesn’t exist with the id and broadcaster_id specified
500 Internal Server Error: Something bad happened on our side

Example Request #1

This request disables a custom reward:


curl -X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
              "is_enabled": false
 }'

Example Response #1

{
    "data": [
        {
            "broadcaster_name": "torpedo09",
            "broadcaster_login": "torpedo09",
            "broadcaster_id": "274637212",
            "id": "92af127c-7326-4483-a52b-b0da0be61c01",
            "image": null,
            "background_color": "#00E5CB",
            "is_enabled": false,
            "cost": 30000,
            "title": "game analysis 2v2",
            "prompt": "",
            "is_user_input_required": false,
            "max_per_stream_setting": {
                "is_enabled": true,
                "max_per_stream": 60
            },
            "max_per_user_per_stream_setting": {
                "is_enabled": false,
                "max_per_user_per_stream": 0
            },
            "global_cooldown_setting": {
                "is_enabled": false,
                "global_cooldown_seconds": 0
            },
            "is_paused": false,
            "is_in_stock": false,
            "default_image": {
                "url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
                "url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
                "url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
            },
            "should_redemptions_skip_request_queue": true,
            "redemptions_redeemed_current_stream": 60,
            "cooldown_expires_at": null
        }
    ]
}

Example Request #2

curl -X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards?broadcaster_id=274637212&id=92af127c-7326-4483-a52b-b0da0be61c01' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
             "title": "game analysis 2v2"
 }'

Example Response #2

 {
    "data": [
        {
            "broadcaster_name": "torpedo09",
            "broadcaster_login": "torpedo09",
            "broadcaster_id": "274637212",
            "id": "92af127c-7326-4483-a52b-b0da0be61c01",
            "image": null,
            "background_color": "",
            "is_enabled": false,
            "cost": 30000,
            "title": "game analysis 2v2",
            "prompt": "",
            "is_user_input_required": false,
            "max_per_stream_setting": {
                "is_enabled": true,
                "max_per_stream": 60
            },
            "max_per_user_per_stream_setting": {
                "is_enabled": false,
                "max_per_user_per_stream": 0
            },
            "global_cooldown_setting": {
                "is_enabled": false,
                "global_cooldown_seconds": 0
            },
            "is_paused": false,
            "is_in_stock": true,
            "default_image": {
                "url_1x": "https://static-cdn.jtvnw.net/custom-reward-images/default-1.png",
                "url_2x": "https://static-cdn.jtvnw.net/custom-reward-images/default-2.png",
                "url_4x": "https://static-cdn.jtvnw.net/custom-reward-images/default-4.png"
            },
            "should_redemptions_skip_request_queue": true,
            "redemptions_redeemed_current_stream": 60,
            "cooldown_expires_at": null
        }
    ]
  }

 

Update Redemption Status

Updates the status of Custom Reward Redemption objects on a channel that are in the UNFULFILLED status.

Only redemptions for a reward created programmatically by the same client_id as attached to the access token can be updated.

Authentication

Query parameter broadcaster_id must match the user_id in the User-Access token

Authorization

Requires OAuth Scope: channel:manage:redemptions

The Custom Reward Redemption specified by id must be for a Custom Reward created by the client_id attached to the access token.

URL

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

Pagination

None. 

Required Query Parameters

Parameter Type Description
id string ID of the Custom Reward Redemption to update, must match a Custom Reward Redemption on broadcaster_id’s channel Max: 50
broadcaster_id string Provided broadcaster_id must match the user_id in the auth token.
reward_id string ID of the Custom Reward the redemptions to be updated are for.

Body Values

Parameter Required Type Description
status Yes string The new status to set redemptions to. Can be either FULFILLED or CANCELED. Updating to CANCELED will refund the user their points.

Return Values

Parameter Type Description
broadcaster_id string The id of the broadcaster that the reward belongs to.
broadcaster_login string Broadcaster’s user login name.
broadcaster_name string The display name of the broadcaster that the reward belongs to.
id string The ID of the redemption.
user_id string The ID of the user that redeemed the reward
user_name string The display name of the user that redeemed the reward.
user_login string The login of the user that redeemed the reward.
reward object Basic information about the Custom Reward that was redeemed at the time it was redeemed. { “id”: string, “title”: string, “prompt”: string, “cost”: int, }
user_input string The user input provided. Null if not provided.
status string One of UNFULFILLED, FULFILLED or CANCELED
redeemed_at string RFC3339 timestamp of when the reward was redeemed.

Response Codes

HTTP Code Meaning
200 OK: A list of the updated Custom Reward Redemptions is returned
400 Bad Request: Query Parameter missing or invalid
401 Unauthenticated: Missing/invalid Token
403 Forbidden: The Custom Reward was created by a different client_id or Channel Points are not available for the broadcaster
404 Not Found: No Custom Reward Redemptions with the specified IDs were found with a status of UNFULFILLED.
500 Internal Server Error: Something bad happened on our side

Example Request

This request updates custom reward redemption status.

curl --X PATCH 'https://api.twitch.tv/helix/channel_points/custom_rewards/redemptions?broadcaster_id=274637212&reward_id=92af127c-7326-4483-a52b-b0da0be61c01&id=17fa2df1-ad76-4804-bfa5-a40ef63efe63' \
-H 'client-id: gx2pv4208cff0ig9ou7nk3riccffxt' \
-H 'Authorization: Bearer vjxv3i0l4zxru966wsnwji51tmpkj2' \
-H 'Content-Type: application/json' \
-d '{
    "status":"CANCELED"
}'

Example Response

{
    "data": [
        {
            "broadcaster_name": "torpedo09",
            "broadcaster_login": "torpedo09",
            "broadcaster_id": "274637212",
            "id": "17fa2df1-ad76-4804-bfa5-a40ef63efe63",
            "user_id": "274637212",
            "user_name": "torpedo09",
            "user_login": "torpedo09",
            "user_input": "",
            "status": "CANCELED",
            "redeemed_at": "2020-07-01T18:37:32Z",
            "reward": {
                "id": "92af127c-7326-4483-a52b-b0da0be61c01",
                "title": "game analysis",
                "prompt": "",
                "cost": 50000
            }
        }
    ]
}

 

Create Clip

Creates a clip programmatically. This returns both an ID and an edit URL for the new clip.

Note: The clips service returns a maximum of 1000 clips,

Clip creation takes time. We recommend that you query Get Clips, with the clip ID that is returned here. If Get Clips returns a valid clip, your clip creation was successful. If, after 15 seconds, you still have not gotten back a valid clip from Get Clips, assume that the clip was not created and retry Create Clip.

This endpoint has a global rate limit, across all callers. The limit may change over time, but the response includes informative headers:

Ratelimit-Helixclipscreation-Limit: <int value>
Ratelimit-Helixclipscreation-Remaining: <int value>

Authentication

  • OAuth token required
  • Required scope: clips:edit

URL

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

Required Query Parameter

Name Type Description
broadcaster_id string ID of the stream from which the clip will be made.

Optional Query Parameter

Name Type Description
has_delay boolean If false, the clip is captured from the live stream when the API is called; otherwise, a delay is added before the clip is captured (to account for the brief delay between the broadcaster’s stream and the viewer’s experience of that stream). Default: false.

Response Fields

Field Type Description
edit_url string URL of the edit page for the clip.
id string ID of the clip that was created.

Example Request

curl -X POST 'https://api.twitch.tv/helix/clips?broadcaster_id=44322889' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
   "data":
   [{
      "id": "FiveWordsForClipSlug",
      "edit_url": "http://clips.twitch.tv/FiveWordsForClipSlug/edit"
   }]
}

Get Clips

Gets clip information by clip ID (one or more), broadcaster ID (one only), or game ID (one only).

Note: The clips service returns a maximum of 1000 clips.

The response has a JSON payload with a data field containing an array of clip information elements and a pagination field containing information required to query for more streams.

Authentication

OAuth or App Access Token required.

URL

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

Required Query Parameter

Name Type Description
broadcaster_id string ID of the broadcaster for whom clips are returned. The number of clips returned is determined by the first query-string parameter (default: 20). Results are ordered by view count.
game_id string ID of the game for which clips are returned. The number of clips returned is determined by the first query-string parameter (default: 20). Results are ordered by view count.
id string ID of the clip being queried. Limit: 100.

For a query to be valid, id (one or more), broadcaster_id, or game_id must be specified. You may specify only one of these parameters.

Optional Query Parameters

Name Type Description
after string Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries specifying broadcaster_id or game_id. The cursor value specified here is from the pagination response field of a prior query.
before string Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries specifying broadcaster_id or game_id. The cursor value specified here is from the pagination response field of a prior query.
ended_at string Ending date/time for returned clips, in RFC3339 format. (Note that the seconds value is ignored.) If this is specified, started_at also must be specified; otherwise, the time period is ignored.
first integer Maximum number of objects to return. Maximum: 100. Default: 20.
started_at string Starting date/time for returned clips, in RFC3339 format. (The seconds value is ignored.) If this is specified, ended_at also should be specified; otherwise, the ended_at date/time will be 1 week after the started_at value.

Response Fields

Field Type Description
id string ID of the clip being queried.
url string URL where the clip can be viewed.
embed_url string URL to embed the clip.
broadcaster_id string User ID of the stream from which the clip was created.
broadcaster_name string Display name corresponding to broadcaster_id.
creator_id string ID of the user who created the clip.
creator_name string Display name corresponding to creator_id.
video_id string ID of the video from which the clip was created.
game_id string ID of the game assigned to the stream when the clip was created.
language string Language of the stream from which the clip was created. A language value is either the ISO 639-1 two-letter code for a supported stream language or “other”.
title string Title of the clip.
view_count int Number of times the clip has been viewed.
created_at string Date when the clip was created.
thumbnail_url string URL of the clip thumbnail.
duration float Duration of the Clip in seconds (up to 0.1 precision).
pagination object containing a string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.

Example Request #1

This gets information for clip AwkwardHelplessSalamanderSwiftRage.

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

Example Response #1

{
  "data": [
    {
      "id": "AwkwardHelplessSalamanderSwiftRage",
      "url": "https://clips.twitch.tv/AwkwardHelplessSalamanderSwiftRage",
      "embed_url": "https://clips.twitch.tv/embed?clip=AwkwardHelplessSalamanderSwiftRage",
      "broadcaster_id": "67955580",
      "broadcaster_name": "ChewieMelodies",
      "creator_id": "53834192",
      "creator_name": "BlackNova03",
      "video_id": "205586603",
      "game_id": "488191",
      "language": "en",
      "title": "babymetal",
      "view_count": 10,
      "created_at": "2017-11-30T22:34:18Z",
      "thumbnail_url": "https://clips-media-assets.twitch.tv/157589949-preview-480x272.jpg",
      "duration": 60
    }
  ]
}

Example Request #2

This gets the top 5 clips from broadcaster 1234.

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

Example Response #2

{
  "data": [
    {
      "id": "RandomClip1",
      "url": "https://clips.twitch.tv/AwkwardHelplessSalamanderSwiftRage",
      "embed_url": "https://clips.twitch.tv/embed?clip=RandomClip1",
      "broadcaster_id": "1234",
      "broadcaster_name": "JJ",
      "creator_id": "123456",
      "creator_name": "MrMarshall",
      "video_id": "1234567",
      "game_id": "33103",
      "language": "en",
      "title": "random1",
      "view_count": 10,
      "created_at": "2017-11-30T22:34:18Z",
      "thumbnail_url": "https://clips-media-assets.twitch.tv/157589949-preview-480x272.jpg",
      "duration": 12.9
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjoiIn0"
  }
}

Get Code Status

Gets the status of one or more provided codes. This API requires that the caller is an authenticated Twitch user. The API is throttled to one request per second per authenticated user. Codes are redeemable alphanumeric strings tied only to the bits product. This third-party API allows other parties to redeem codes on behalf of users. Third-party app and extension developers can use the API to provide rewards of bits from within their games.

We provide sets of codes to the third party as part of a contract agreement. The third-party program then calls this API to credit a Twitch user by submitting any specific codes. This means that a bits reward can be applied without users having to follow any manual steps.

All codes are single-use. Once a code has been redeemed, via either this API or the site page, then the code is no longer valid for any further use.

URL

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

Authentication

Access is controlled via an app access token on the calling service. The client ID associated with the app access token must be approved by Twitch as part of a contracted arrangement.

Authorization

Callers with an app access token are authorized to redeem codes on behalf of any Twitch user account.

Query Parameters

Param Type Description
code String The code to get the status of. Repeat this query parameter additional times to get the status of multiple codes.
Ex: ?code=code1&code=code2
1-20 code parameters are allowed.
user_id Integer Represents a numeric Twitch user ID.
The user account which is going to receive the entitlement associated with the code.

Return Values

Param Type Description
data Array of payloads each of which includes code (string) and status (string). Indicates the current status of each key when checking key status. 

Indicates the success or error state of each key when redeeming.

Code Statuses

Code Description
SUCCESSFULLY_REDEEMED Request successfully redeemed this code to the authenticated user’s account.This status will only ever be encountered when calling the POST API to redeem a key.
ALREADY_CLAIMED Code has already been claimed by a Twitch user.
EXPIRED Code has expired and can no longer be claimed.
USER_NOT_ELIGIBLE User is not eligible to redeem this code.
NOT_FOUND Code is not valid and/or does not exist in our database.
INACTIVE Code is not currently active.
UNUSED Code has not been claimed.This status will only ever be encountered when calling the GET API to get a keys status.
INCORRECT_FORMAT Code was not properly formatted.
INTERNAL_ERROR Indicates some internal and/or unknown failure handling this code.

 

Example Request

curl -X GET 'https://api.twitch.tv/helix/entitlements/codes?code=KUHXV-4GXYP-AKAKK&code=XZDDZ-5SIQR-RT5M3&user_id=156900877' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data":[
    {
      "code":"KUHXV-4GXYP-AKAKK",
      "status":"UNUSED"
    },
    {
      "code":"XZDDZ-5SIQR-RT5M3",
      "status":"ALREADY_CLAIMED"
    }
  ]
}

 

Get Drops Entitlements

Gets a list of entitlements for a given organization that have been granted to a game, user, or both.

Authentication

App Access OAuth Token required.

Authorization

OAuth Token Client ID must have ownership of Game:

  • Client ID > Organization ID > Game ID

Pagination support

Forward only

URL

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

Required Query Parameters

None

Optional Query Parameters

Parameter Type Description
id string Unique Identifier of the entitlement
user_id string A Twitch User ID
game_id string A Twitch Game ID
after string The cursor used to fetch the next page of data.
first integer Maximum number of entitlements to return.
Default: 20
Max: 1000

Valid combinations of requests are:

Authorization Provided Request Fields Present Data Returned
App Access
OAuth Token
 
No fields All entitlements with benefits owned by your organization.
  user_id All entitlements for a user with benefits owned by your organization.
  user_id, game_id All entitlements for the game granted to a user. Your organization must own the game.
  game_id All entitlements for all users for a game. Your organization must own the game.
User OAuth Token No fields All entitlements owned by that user with benefits owned by your organization.
  user_id Invalid
  user_id, game_id Invalid
  game_id All entitlements owned by a user for the specified game. Your organization must own the game.

Return Values

Parameter Type Description
data array Array of entitlements
id string Unique Identifier of the entitlement
benefit_id string Identifier of the Benefit
timestamp string UTC timestamp in ISO format when this entitlement was granted on Twitch.
user_id string Twitch User ID of the user who was granted the entitlement.
game_id string Twitch Game ID of the game that was being played when this benefit was entitled.
pagination object containing a string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.

Response Codes

HTTP CodeMeaning
200 OKResource found
400 Bad Request
  • Malformed request
  • User ID not valid
  • Game ID not valid
401 Unauthorized
  • API handles authorization
  • Client ID not owned by Organization
429 Rate LimitAPI will handle rate limiting
500 Internal Server Error 
503 Service Unavailable 

Example Request

curl -H GET 'helix/entitlements/drops?user_id=25009227&game_id=33214' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "fb78259e-fb81-4d1b-8333-34a06ffc24c0",
      "benefit_id": "74c52265-e214-48a6-91b9-23b6014e8041",
      "timestamp": "2019-01-28T04:17:53.325Z",
      "user_id": "25009227",
      "game_id": "33214"
    },
    {
      "id": "862750a5-265e-4ab6-9f0a-c64df3d54dd0",
      "benefit_id": "74c52265-e214-48a6-91b9-23b6014e8041",
      "timestamp": "2019-01-28T04:16:53.325Z",
      "user_id": "25009227",
      "game_id": "33214"
    },
    {
      "id": "d8879baa-3966-4d10-8856-15fdd62cce02",
      "benefit_id": "cdfdc5c3-65a2-43bc-8767-fde06eb4ab2c",
      "timestamp": "2019-01-28T04:15:53.325Z",
      "user_id": "25009227",
      "game_id": "33214"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudW..."
  }
}

Redeem Code

Redeems one or more provided codes to the authenticated Twitch user. This API requires that the caller is an authenticated Twitch user. This API requires that the caller is an authenticated Twitch user. The API is throttled to one request per second per authenticated user. Codes are redeemable alphanumeric strings tied only to the bits product. This third-party API allows other parties to redeem codes on behalf of users. Third-party app and extension developers can use the API to provide rewards of bits from within their games. We provide sets of codes to the third party as part of a contract agreement. The third-party program then calls this API to credit the Twitch user by submitting any specific codes. This means that a bits reward can be applied without the user having to follow any manual steps.

All codes are single-use. Once a code has been redeemed, via either this API or the site page, the code is no longer valid for any further use.

URL

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

Authentication

Access is controlled via an app access token on the calling service. The client ID associated with the app access token must be approved by Twitch.

Authorization

Callers with an app access token are authorized to redeem codes on behalf of any Twitch user account.

Query Parameters

Parameter Type Description
code String The code to redeem to the authenticated user’s account.

A fifteen character (plus optional hyphen separators) alphanumeric string, e.g. ABCDE-12345-FGHIJ

Repeat this query parameter additional times to redeem multiple codes.
Ex: ?code=code1&code=code2
1-20 code parameters are allowed.
user_id Integer Represents a numeric Twitch user ID.
The user account which is going to receive the entitlement associated with the code.

Return Values

Parameter Type Description
data Array of payloads each of which includes code (string) and status (string). Indicates the success or error state of each key when redeeming. 

Code Statuses

Code Description
SUCCESSFULLY_REDEEMED Request successfully redeemed this code to the authenticated user’s account. This status will only ever be encountered when calling the POST API to redeem a key.
ALREADY_CLAIMED Code has already been claimed by a Twitch user.
EXPIRED Code has expired and can no longer be claimed.
USER_NOT_ELIGIBLE User is not eligible to redeem this code.
NOT_FOUND Code is not valid and/or does not exist in our database.
INACTIVE Code is not currently active.
UNUSED Code has not been claimed. This status will only ever be encountered when calling the GET API to get a key’s status.
INCORRECT_FORMAT Code was not properly formatted.
INTERNAL_ERROR Indicates some internal and/or unknown failure handling this code.

 

Example Request

curl -X POST 'https://api.twitch.tv/helix/entitlements/codes?code=8CD5P-V3J92-2S6JY&code=PUN4G-HYFVP-MMFET' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data":[
    {
      "code":"8CD5P-V3J92-2S6JY",
      "status":"SUCCESSFULLY_REDEEMED"
    },
    {
      "code":"PUN4G-HYFVP-MMFET",
      "status":"ALREADY_CLAIMED"
    }
  ]
}

 

 

Create EventSub Subscription

Creates an EventSub subscription.

Authentication

  • App Access Token

URL

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

Required Query Parameters

None

Required Body Parameters

Parameter Type Description
type string The category of the subscription that is being created. Valid subscription types can be found here.
version string The version of the subscription type that is being created. Each subscription type has independent versioning.
condition condition JSON object containing custom parameters for a particular subscription.
transport transport JSON object containing notification delivery specific configuration including a method string. Valid transport methods include: webhook. In addition to the method string, a webhook transport must include the callback and secret information.

Response Fields

Field Type Description
data array Array containing 1 element: the created subscription.
id string ID of the subscription created.
status string Status of the subscription. Valid values are:

enabled: designates that the subscription is in an operable state and is valid.

webhook_callback_verification_pending: webhook is pending verification of the callback specified in the subscription creation request.

webhook_callback_verification_failed: webhook failed verification of the callback specified in the subscription creation request.

notification_failures_exceeded: notification delivery failure rate was too high.

authorization_revoked: authorization for user(s) in the condition was revoked.

user_removed: a user in the condition of the subscription was removed.
type string The category of the subscription that was created.
version string The version of the subscription type that was created.
condition condition JSON object specifying custom parameters for the subscription.
created_at string RFC3339 timestamp indicating when the subscription was created.
transport transport JSON object indicating the notification delivery specific information. Includes the transport method and callback URL.
total integer Total number of subscriptions for the client ID that made the subscription creation request.
total_cost integer Total cost of all the subscriptions for the client ID that made the subscription creation request.
max_total_cost integer The maximum total cost allowed for all of the subscriptions for the client ID that made the subscription creation request.

Example Request

.

curl -X POST 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
-d '{"type":"users.update","version":"1","condition":{"user_id":"1234"},"transport":{"method":"webhook","callback":"https://this-is-a-callback.com","secret":"s3cre7"}}'

Example Response

{
  "data": [
    {
      "id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
      "status": "webhook_callback_verification_pending",
      "type": "users.update",
      "version": "1",
      "condition": {
        "user_id": "1234"
      },
      "created_at": "2020-11-10T20:29:44Z",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback.com"
      },
      "cost": 1
    }
  ],
  "total": 1,
  "total_cost": 1,
  "max_total_cost": 10000
}

Delete EventSub Subscription

Delete an EventSub subscription.

Authentication

  • App Access Token

URL

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

Required Query Parameters

Name Type Description
id string The subscription ID for the subscription you want to delete.

Response Fields

None

Response Codes

Code Meaning
204 Subscription deleted successfully.

Example Request

Deletes an EventSub subscription.

curl -X DELETE 'https://api.twitch.tv/helix/eventsub/subscriptions?id=26b1c993-bfcf-44d9-b876-379dacafe75a' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \

Example Response

204 No Content

Get EventSub Subscriptions

Get a list of your EventSub subscriptions. The subscriptions are paginated and ordered by most recent first.

Authentication

  • App Access Token

URL

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

Required Query Parameters

None

Optional Query Parameters

Use parameters to filter by subscription status or type. Only include one filter query parameter; if you specify both status and type parameters, you will receive an error response.

Parameter Type Description
status string Include this parameter to filter subscriptions by one status type. Valid values:

enabled: the subscription is in an operable state and is valid.

webhook_callback_verification_pending: subscription is pending verification of the callback specified in the subscription creation request.

webhook_callback_verification_failed: subscription failed verification of the callback specified in the subscription creation request.

notification_failures_exceeded: notification delivery failure rate was too high.

authorization_revoked: authorization for user(s) in the condition was revoked.

user_removed: a user in the condition of the subscription was removed.
type string Include this parameter to filter subscriptions by subscription type name (e.g., channel.update).

Response Fields

Field Type Description
data array Array containing subscriptions.
id string ID of the subscription.
status string Status of the subscription. Valid values are:

enabled: designates that the subscription is in an operable state and is valid.

webhook_callback_verification_pending: webhook is pending verification of the callback specified in the subscription creation request.

webhook_callback_verification_failed: webhook failed verification of the callback specified in the subscription creation request.

notification_failures_exceeded: notification delivery failure rate was too high.

authorization_revoked: authorization for user(s) in the condition was revoked.

user_removed: a user in the condition of the subscription was removed.
type string The category of the subscription.
version string The version of the subscription.
condition condition JSON object specifying custom parameters for the subscription.
created_at string RFC3339 timestamp indicating when the subscription was created.
transport transport JSON object indicating the notification delivery specific information. Includes the transport method and callback URL.
total integer Total number of subscriptions for the client ID that made the subscription creation request.
total_cost integer Total cost of all the subscriptions for the client ID that made the subscription creation request.
max_total_cost integer The maximum total cost allowed for all of the subscriptions for the client ID that made the subscription creation request.
pagination object A cursor value to be used in a subsequent request to specify the starting point of the next set of results.

Example Request

Get a list of your EventSub subscriptions. The subscriptions are paginated and ordered by most recent first.

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

Example Response

{
  "total": 2,
  "data": [
    {
      "id": "26b1c993-bfcf-44d9-b876-379dacafe75a",
      "status": "enabled",
      "type": "streams.online",
      "version": "1",
      "condition": {
        "broadcaster_user_id": "1234"
      },
      "created_at": "2020-11-10T20:08:33Z",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback.com"
      },
      "cost": 1
    },
    {
      "id": "35016908-41ff-33ce-7879-61b8dfc2ee16",
      "status": "webhook-callback-verification-pending",
      "type": "users.update",
      "version": "1",
      "condition": {
        "user_id": "1234"
      },
      "created_at": "2020-11-10T20:31:52Z",
      "transport": {
        "method": "webhook",
        "callback": "https://this-is-a-callback.com"
      },
      "cost": 0
    }
  ],
  "total_cost": 1,
  "max_total_cost": 10000,
  "pagination": {}
}

Get Top Games

Gets games sorted by number of current viewers on Twitch, most popular first.

The response has a JSON payload with a data field containing an array of games information elements and a pagination field containing information required to query for more streams.

Authentication

OAuth or App Access Token required.

URL

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

Required Query Parameters

None

Optional Query Parameters

Name Type Description
after string Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
before string Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
first integer Maximum number of objects to return. Maximum: 100. Default: 20.

Response Fields

Field Type Description
box_art_url object Template URL for a game’s box art.
id string Game ID.
name string Game name.
pagination object containing a string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.

Example Request

This gets the 20 currently most-viewed games.

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

Example Response

{
  "data": [
    {
      "id": "493057",
      "name": "PLAYERUNKNOWN'S BATTLEGROUNDS",
      "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/PLAYERUNKNOWN%27S%20BATTLEGROUNDS-{width}x{height}.jpg"
    },
    ...
  ],
  "pagination":{"cursor":"eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6MjB9fQ=="}
}

Get Games

Gets game information by game ID or name.

The response has a JSON payload with a data field containing an array of games elements.

Authentication

OAuth or App Access Token required.

URL

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

Required Query Parameters

Name Type Description
id string Game ID. At most 100 id values can be specified.
name string Game name. The name must be an exact match. For example, “Pokemon” will not return a list of Pokemon games; instead, query any specific Pokemon games in which you are interested. At most 100 name values can be specified.

For a query to be valid, name and/or id must be specified.

Optional Query Parameters

None

Response Fields

Fields Type Description
box_art_url object Template URL for the game’s box art.
id string Game ID.
name string Game name.

Example Request

This gets information for game ID 493057.

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

Example Response

{
    "data": [
        {
            "box_art_url": "https://static-cdn.jtvnw.net/ttv-boxart/Fortnite-52x72.jpg",
            "id": "33214",
            "name": "Fortnite"
        }
    ... ],
    "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN"
  }
}

Get Hype Train Events

Description

Gets the information of the most recent Hype Train of the given channel ID. When there is currently an active Hype Train, it returns information about that Hype Train. When there is currently no active Hype Train, it returns information about the most recent Hype Train. After 5 days, if no Hype Train has been active, the endpoint will return an empty response.

Authentication

  • User OAuth Token or App Access Token
  • Required scope: channel:read:hype_train

URL

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

Required Query Parameter

Parameter Type Description
broadcaster_id string User ID of the broadcaster. Must match the User ID in the Bearer token if User Token is used.

Optional Query Parameters

Parameter Type Description
first integer Maximum number of objects to return. Maximum: 100. Default: 1.
id string The id of the wanted event, if known
cursor string Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without id. If an ID is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query.

Return Values

Parameter Type Description
id string The distinct ID of the event
event_type string Displays hypetrain.{event_name}, currently only hypetrain.progression
event_timestamp string RFC3339 formatted timestamp of event
version string Returns the version of the endpoint
event_data object (See below for the schema)
  id string The distinct ID of this Hype Train
  broadcaster_id string Channel ID of which Hype Train events the clients are interested in
  started_at string RFC3339 formatted timestamp of when this Hype Train started
  expires_at string RFC3339 formatted timestamp of the expiration time of this Hype Train
  cooldown_end_time string RFC3339 formatted timestamp of when another Hype Train can be started again
  level integer The highest level (in the scale of 1-5) reached of the Hype Train
  goal integer The goal value of the level above
  total integer The total score so far towards completing the level goal above
  top_contributions object An array of top contribution objects, one object for each type.  For example, one object would represent top contributor of BITS, by aggregate, and one would represent top contributor of SUBS by count.
    total integer Total aggregated amount of all contributions by the top contributor. If type is BITS, total represents aggregate amount of bits used.  If type is SUBS, aggregate total where 500, 1000, or 2500 represent tier 1, 2, or 3 subscriptions respectively.  For example, if top contributor has gifted a tier 1, 2, and 3 subscription, total would be 4000.
    type string Identifies the contribution method, either BITS or SUBS
    user string ID of the contributing user
last_contribution object An object that represents the most recent contribution
    total integer Total amount contributed. If type is BITS, total represents amounts of bits used.  If type is SUBS, total is 500, 1000, or 2500 to represent tier 1, 2, or 3 subscriptions respectively
    type string Identifies the contribution method, either BITS or SUBS
    user string ID of the contributing user
pagination string A cursor value, to be used in a subsequent requests to specify the starting point of the next set of results

Example Request

curl -X GET
'https://api.twitch.tv/helix/hypetrain/events?broadcaster_id=270954519&first=1' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "1b0AsbInCHZW2SQFQkCzqN07Ib2",
      "event_type": "hypetrain.progression",
      "event_timestamp": "2020-04-24T20:07:24Z",
      "version": "1.0",
      "event_data": {
        "broadcaster_id": "270954519",
        "cooldown_end_time": "2020-04-24T20:13:21.003802269Z",
        "expires_at": "2020-04-24T20:12:21.003802269Z",
        "goal": 1800,
        "id": "70f0c7d8-ff60-4c50-b138-f3a352833b50",
        "last_contribution": {
          "total": 200,
          "type": "BITS",
          "user": "134247454"
        },
        "level": 2,
        "started_at": "2020-04-24T20:05:47.30473127Z",
        "top_contributions": [
          {
            "total": 600,
            "type": "BITS",
            "user": "134247450"
          }
        ],
        "total": 600
      }
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjI3MDk1NDUxOToxNTg3NzU4ODQ0OjFiMEFzYkluQ0haVzJTUUZRa0N6cU4wN0liMiJ9fQ"
  }
}

Check AutoMod Status

Determines whether a string message meets the channel’s AutoMod requirements.

AutoMod is a moderation tool that blocks inappropriate or harassing chat with powerful moderator control. AutoMod detects misspellings and evasive language automatically. AutoMod uses machine learning and natural language processing algorithms to hold risky messages from chat so they can be reviewed by a channel moderator before appearing to other viewers in the chat. Moderators can approve or deny any message caught by AutoMod. 

For more information about AutoMod, see How to Use AutoMod.

Authorization

  • OAuth token required
  • Required Scope: moderation:read

URL

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

Pagination Support

None.

Query Parameter

Parameter Required Type Description
broadcaster_id yes string Provided broadcaster_id must match the user_id in the auth token.

Body Parameters

Parameter Required Type Description
msg_id yes string Developer-generated identifier for mapping messages to results.
msg_text yes string Message text.
user_id yes string User ID of the sender.

Return Values

Parameter Type Description
msg_id string The msg_id passed in the body of the POST message. Maps each message to its status.
is_permitted Boolean Indicates if this message meets AutoMod requirements.

 

Example Request

Checks to see if the messages “Hello World!” and “Boooooo!” meets AutoMod requirements.

curl -X POST 'https://api.twitch.tv/helix/moderation/enforcements/status' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-d '{
  "data": [
    {
      "msg_id": "123",
      "msg_text": "Hello World!",
      "user_id": "23749"
    },
    {
      "msg_id": "393",
      "msg_text": "Boooooo!",
      "user_id": "23422"
    }
  ]
}'

Example Response

Shows that message ID 123 meets the requirements and message ID 393 does not.

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

 

Manage Held AutoMod Messages

Allow or deny a message that was held for review by AutoMod.

In order to retrieve messages held for review, use the chat_moderator_actions topic via PubSub. For more information about AutoMod, see How to Use AutoMod.

Authorization

  • User OAuth token required
  • Required Scope: moderator:manage:automod

Note that the scope allows this endpoint to be used for any channel that the authenticated user is a moderator, including their own channel.

URL

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

Required Body Parameters

Parameter Type Description
user_id string The moderator who is approving or rejecting the held message. Must match the user_id in the user OAuth token.
msg_id string ID of the message to be allowed or denied. These message IDs are retrieved from PubSub as mentioned above. Only one message ID can be provided.
action string The action to take for the message. Must be "ALLOW" or "DENY".

Response Codes

Code Meaning
204 Message was approved or denied successfully.
400 Message was already processed or an invalid action was provided.
401 Authentication failure.
403 Requesting user is not authorized to process messages for this channel.
404 Message not found or invalid msg_id.

Example Request 1

Allow a message being held by AutoMod.

curl -X POST 'https://api.twitch.tv/helix/moderation/automod/message' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-d '{
  "user_id": "9327994",
  "msg_id": "836013710",
  "action": "ALLOW"
}'

Example Response 1

Shows that a message was successfully allowed.

204 No Content

Example Request 2

Deny a message being held by AutoMod.

curl -X POST 'https://api.twitch.tv/helix/moderation/automod/message' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-d '{
  "user_id": "9327994",
  "msg_id": "836013710",
  "action": "DENY"
}'

Example Response 2

Shows that a message was successfully denied.

204 No Content

Get Banned Events

Returns all user bans and un-bans in a channel.

Authorization

  • OAuth token required
  • Required Scope: moderation:read

URL

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

Pagination Support

Forward pagination.

Required Query Parameter

Parameter Required Type Description
broadcaster_id yes string Provided broadcaster_id must match the user_id in the auth token.

Maximum: 1

Optional Query Parameters

Parameter Required Type Description
user_id no string Filters the results and only returns a status object for ban events that include users being banned or un-banned in this channel and have a matching user_id.

Format: Repeated Query Parameter, eg. /moderation/banned/events?broadcaster_id=1&user_id=2&user_id=3

Maximum: 100
after no string Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without user_id. If a user_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query.
first no string Maximum number of objects to return. Maximum: 100. Default: 20.

Return Values

Parameter Type Description
id string Event ID
event_type string Displays moderation.user.ban or moderation.user.unban
event_timestamp string RFC3339 formatted timestamp for events.
pagination object containing a string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.
version string Returns the version of the endpoint.
event_data strings Returns broadcaster_id, broadcaster_login, broadcaster_name, user_id, user_login, user_name, and expires_at.

Example Request

Returns all bans and un-bans for Broadcaster 198704263.

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

Example Response

{
  "data": [
    {
      "id": "1IPFqAb0p0JncbPSTEPhx8JF1Sa",
      "event_type": "moderation.user.ban",
      "event_timestamp": "2019-03-13T15:55:14Z",
      "version": "1.0",
      "event_data": {
        "broadcaster_id": "198704263",
        "broadcaster_login": "racageneg",
        "broadcaster_name": "racageneg",
        "user_id": "424596340",
        "user_login": "quotrok",
        "user_name": "quotrok",
        "expires_at": ""
      }
    },
    {
      "id": "1IPFsDv5cs4mxfJ1s2O9Q5flf4Y",
      "event_type": "moderation.user.unban",
      "event_timestamp": "2019-03-13T15:55:30Z",
      "version": "1.0",
      "event_data": {
        "broadcaster_id": "198704263",
        "broadcaster_login": "racageneg",
        "broadcaster_name": "racageneg",
        "user_id": "424596340",
        "user_login": "quotrok",
        "user_name": "quotrok",
        "expires_at": ""
      }
    },
    {
      "id": "1IPFqmlu9W2q4mXXjULyM8zX0rb",
      "event_type": "moderation.user.ban",
      "event_timestamp": "2019-03-13T15:55:19Z",
      "version": "1.0",
      "event_data": {
        "broadcaster_id": "198704263",
        "broadcaster_login": "racageneg",
        "broadcaster_name": "racageneg",
        "user_id": "424596340",
        "user_login": "quotrok",
        "user_name": "quotrok",
        "expires_at": ""
      }
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjE5OTYwNDI2MzoyMDIxMjA1MzE6MUlQRnFtbHU5VzJxNG1YWGpVTHlNOHpYMHJiIn19"
  }
}

Get Banned Users

Returns all banned and timed-out users in a channel.

Authentication

  • OAuth token required
  • Required scope: moderation:read

URL

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

Pagination Support

Forward and reverse pagination.

Required Query Parameter

ParameterRequiredTypeDescription
broadcaster_idyesstringProvided broadcaster_id must match the user_id in the auth token.

Maximum: 1

Optional Query Parameters

ParameterRequiredTypeDescription
user_idnostringFilters the results and only returns a status object for users who are banned in this channel and have a matching user_id.

Format: Repeated Query Parameter, eg. /moderation/banned?broadcaster_id=1&user_id=2&user_id=3

Maximum: 100
firstnostringMaximum number of objects to return. Maximum: 100. Default: 20.
afternostringCursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without user_id. If a user_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query.
beforenostringCursor for backward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without user_id. If a user_id is specified, it supersedes any cursor/offset. combinations. The cursor value specified here is from the pagination response field of a prior query.

Return Values

Parameter Type Description
user_id string User ID of a user who has been banned.
user_login string Login of a user who has been banned.
user_name string Display name of a user who has been banned.
expires_at string  
pagination object containing a string  

Example Request

Gets the users who have been banned by Broadcaster 198704263.

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

Example Response

Shows that users glowillig and quotrok have been banned.

{
  "data": [
    {
      "user_id": "423374343",
      "user_login": "glowillig",
      "user_name": "glowillig",
      "expires_at": "2019-03-15T02:00:28Z"
    },
    {
      "user_id": "424596340",
      "user_login": "quotrok",
      "user_name": "quotrok",
      "expires_at": "2018-08-07T02:07:55Z"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
  }
}

Get Moderators

Returns all moderators in a channel. Note: This endpoint does not return the broadcaster in the response, as broadcasters are channel owners and have all permissions of moderators implicitly.

Authorization

  • OAuth token required
  • Required scope: moderation:read

URL

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

Pagination Support

Forward pagination only.

Required Query Parameter

Parameter Type Description
broadcaster_id string Provided broadcaster_id must match the user_id in the auth token. Maximum: 1

Optional Query Parameters

ParameterTypeDescription
user_idstringFilters the results and only returns a status object for users who are moderators in this channel and have a matching user_id.

Format: Repeated Query Parameter, eg. /moderation/moderators?broadcaster_id=1&user_id=2&user_id=3

Maximum: 100
firststringMaximum number of objects to return. Maximum: 100. Default: 20.
afterstringCursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without user_id. If a user_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query.

Return Values

Parameter Type Description
user_id string User ID of a moderator in the channel.
user_login string Login of a moderator in the channel.
user_name string Display name of a moderator in the channel.
pagination object containing a string A cursor value, to be used in subsequent requests to specify the starting point of the next set of results.

Example Request

This request returns any moderators for Broadcaster ID 198704263.

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

Example Response

{
  "data": [
    {
      "user_id": "424596340",
      "user_login": "quotrok",
      "user_name": "quotrok"
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
  }
}

 

 

Get Moderator Events

Returns a list of moderators or users added and removed as moderators from a channel.

Authorization

  • OAuth token required
  • Required scope: moderation:read

URL

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

Pagination Support

Forward pagination only.

Required Query Parameter

Parameter Type Description
broadcaster_id string Provided broadcaster_id must match the user_id in the auth token.

Maximum: 1

Optional Query Parameter

Parameter Type Description
user_id string Filters the results and only returns a status object for users who have been added or removed as moderators in this channel and have a matching user_id.

Format: Repeated Query Parameter, e.g. /moderation/moderators/events?broadcaster_id=1&user_id=2&user_id=3

Maximum: 100
after string Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without user_id. If a user_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query.
first string Maximum number of objects to return. Maximum: 100. Default: 20.

Return Values

Parameter Type Description
id string User ID of the moderator.
event_type string Displays moderation.moderator.add or moderation.moderator.remove
event_timestamp string RFC3339 formatted timestamp for events.
pagination object containing a string A cursor value to be used in a subsequent request to specify the starting point of the next set of results.
version string Returns the version of the endpoint.
broadcaster_id string ID of the broadcaster adding or removing moderators.
broadcaster_login string Login of the broadcaster.
broadcaster_name string Name of the broadcaster.
user_id string ID of the user being added or removed as moderator.
user_login string Login of the user.
user_name string Name of the user.

Example Request

Returns users added or removed as moderators for Broadcaster ID 198704263.

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

Example Response

{
  "data": [
    {
      "id": "1IVBTnDSUDApiBQW4UBcVTK4hPr",
      "event_type": "moderation.moderator.remove",
      "event_timestamp": "2019-03-15T18:18:14Z",
      "version": "1.0",
      "event_data": {
        "broadcaster_id": "198704263",
        "broadcaster_login": "aan22209",
        "broadcaster_name": "aan22209",
        "user_id": "423374343",
        "user_login": "glowillig",
        "user_name": "glowillig"
      }
    },
    {
      "id": "1IVIPQdYIEnD8nJ376qkASDzsj7",
      "event_type": "moderation.moderator.add",
      "event_timestamp": "2019-03-15T19:15:13Z",
      "version": "1.0",
      "event_data": {
        "broadcaster_id": "198704263",
        "broadcaster_login": "aan22209",
        "broadcaster_name": "aan22209",
        "user_id": "423374343",
        "user_login": "glowillig",
        "user_name": "glowillig"
      }
    },
    {
      "id": "1IVBTP7gG61oXLMu7fvnRhrpsro",
      "event_type": "moderation.moderator.remove",
      "event_timestamp": "2019-03-15T18:18:11Z",
      "version": "1.0",
      "event_data": {
        "broadcaster_id": "198704263",
        "broadcaster_login": "aan22209",
        "broadcaster_name": "aan22209",
        "user_id": "424596340",
        "user_login": "quotrok",
        "user_name": "quotrok"
      }
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
  }
}

Get Polls

NEW Get information about all polls or specific polls for a Twitch channel. Poll information is available for 90 days.

BETA This endpoint is currently available as part of a public beta and should not be used in production environments. See Product Lifecycle for more information regarding the expectations of beta versions.

Authorization

  • User OAuth token
  • Required scope: channel:read:polls

URL

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

Pagination Support

Forward pagination.

Required Query Parameter

Parameter Type Description
broadcaster_id string The broadcaster running polls. Provided broadcaster_id must match the user_id in the user OAuth token.

Maximum: 1

Optional Query Parameter

Parameter Type Description
id string ID of a poll. Filters results to one or more specific polls. Not providing one or more IDs will return the full list of polls for the authenticated channel.

Maximum: 100
after string Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
first string Maximum number of objects to return.

Maximum: 20. Default: 20.

Return Values

Parameter Type Description
id string ID of the poll.
broadcaster_id string ID of the broadcaster.
broadcaster_name string Name of the broadcaster.
broadcaster_login string Login of the broadcaster.
title string Question displayed for the poll.
choices object[] Array of the poll choices.
choice.id string ID for the choice.
choice.title string Text displayed for the choice.
choice.votes integer Total number of votes received for the choice across all methods of voting.
choice.channel_points_votes integer Number of votes received via Channel Points.
choice.bits_votes integer Number of votes received via Bits.
bits_voting_enabled boolean Indicates if Bits can be used for voting.
bits_per_vote integer Number of Bits required to vote once with Bits.
channel_points_voting_enabled boolean Indicates if Channel Points can be used for voting.
channel_points_per_vote integer Number of Channel Points required to vote once with Channel Points.
status string Poll status. Valid values are:

ACTIVE: Poll is currently in progress.

COMPLETED: Poll has reached its ended_at time.

TERMINATED: Poll has been manually terminated before its ended_at time.

ARCHIVED: Poll is no longer visible on the channel.

MODERATED: Poll is no longer visible to any user on Twitch.

INVALID: Something went wrong determining the state.
duration integer Total duration for the poll (in seconds).
started_at string UTC timestamp for the poll’s start time.
ended_at string UTC timestamp for the poll’s end time. Set to null if the poll is active.

Response Codes

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

Example Request

Returns information for a specific poll created for the TwitchDev channel.

curl -X GET 'https://api.twitch.tv/helix/polls?broadcaster_id=141981764&id=ed961efd-8a3f-4cf5-a9d0-e616c590cd2a' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
      "broadcaster_id": "55696719",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Heads or Tails?",
      "choices": [
        {
          "id": "4c123012-1351-4f33-84b7-43856e7a0f47",
          "title": "Heads",
          "votes": 0,
          "channel_points_votes": 0,
          "bits_votes": 0
        },
        {
          "id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
          "title": "Tails",
          "votes": 0,
          "channel_points_votes": 0,
          "bits_votes": 0
        }
      ],
      "bits_voting_enabled": false,
      "bits_per_vote": 0,
      "channel_points_voting_enabled": false,
      "channel_points_per_vote": 0,
      "status": "ACTIVE",
      "duration": 1800,
      "started_at": "2021-03-19T06:08:33.871278372Z"
    }
  ],
  "pagination": {}
}

Create Poll

NEW Create a poll for a specific Twitch channel.

BETA This endpoint is currently available as part of a public beta and should not be used in production environments. See Product Lifecycle for more information regarding the expectations of beta versions.

Authorization

  • User OAuth token
  • Required scope: channel:manage:polls

URL

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

Required Body Parameter

Parameter Type Description
broadcaster_id string The broadcaster running polls. Provided broadcaster_id must match the user_id in the user OAuth token.

Maximum: 1
title string Question displayed for the poll.

Maximum: 60 characters.
choices object[] Array of the poll choices.

Minimum: 2 choices. Maximum: 5 choices.
choice.title string Text displayed for the choice.

Maximum: 25 characters.
duration integer Total duration for the poll (in seconds).

Minimum: 15. Maximum: 1800.

Optional Body Parameter

Parameter Type Description
bits_voting_enabled boolean Indicates if Bits can be used for voting.

Default: false
bits_per_vote integer Number of Bits required to vote once with Bits.

Minimum: 0. Maximum: 10000.
channel_points_voting_enabled boolean Indicates if Channel Points can be used for voting.

Default: false
channel_points_per_vote integer Number of Channel Points required to vote once with Channel Points.

Minimum: 0. Maximum: 1000000.

Return Values

Parameter Type Description
id string ID of the poll.
broadcaster_id string ID of the broadcaster.
broadcaster_name string Name of the broadcaster.
broadcaster_login string Login of the broadcaster.
title string Question displayed for the poll.
choices object[] Array of the poll choices.
choice.id string ID for the choice.
choice.title string Text displayed for the choice.
choice.votes integer Total number of votes received for the choice.
choice.channel_points_votes integer Number of votes received via Channel Points.
choice.bits_votes integer Number of votes received via Bits.
bits_voting_enabled boolean Indicates if Bits can be used for voting.
bits_per_vote integer Number of Bits required to vote once with Bits.
channel_points_voting_enabled boolean Indicates if Channel Points can be used for voting.
channel_points_per_vote integer Number of Channel Points required to vote once with Channel Points.
status string Poll status. Valid values are:

ACTIVE: Poll is currently in progress.

COMPLETED: Poll has reached its ended_at time.

TERMINATED: Poll has been manually terminated before its ended_at time.

ARCHIVED: Poll is no longer visible on the channel.

MODERATED: Poll is no longer visible to any user on Twitch.

INVALID: Something went wrong determining the state.
duration integer Total duration for the poll (in seconds).
started_at string UTC timestamp for the poll’s start time.
ended_at string UTC timestamp for the poll’s end time. Set to null if the poll is active.

Response Codes

Code Meaning
200 Poll created successfully.
400 Request was invalid.
401 Authorization failed.

Example Request

Returns information for a specific poll created for the TwitchDev channel.

curl -X POST 'https://api.twitch.tv/helix/polls' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "broadcaster_id":"141981764",
  "title":"Heads or Tails?",
  "choices":[{
    "title":"Heads"
  },
  {
    "title":"Tails"
  }],
  "channel_points_voting_enabled":true,
  "channel_points_per_vote":100,
  "duration":1800
}'

Example Response

{
  "data": [
    {
      "id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Heads or Tails?",
      "choices": [
        {
          "id": "4c123012-1351-4f33-84b7-43856e7a0f47",
          "title": "Heads",
          "votes": 0,
          "channel_points_votes": 0,
          "bits_votes": 0
        },
        {
          "id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
          "title": "Tails",
          "votes": 0,
          "channel_points_votes": 0,
          "bits_votes": 0
        }
      ],
      "bits_voting_enabled": false,
      "bits_per_vote": 0,
      "channel_points_voting_enabled": true,
      "channel_points_per_vote": 100,
      "status": "ACTIVE",
      "duration": 1800,
      "started_at": "2021-03-19T06:08:33.871278372Z"
    }
  ]
}

End Poll

NEW End a poll that is currently active.

BETA This endpoint is currently available as part of a public beta and should not be used in production environments. See Product Lifecycle for more information regarding the expectations of beta versions.

Authorization

  • User OAuth token
  • Required scope: channel:manage:polls

URL

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

Required Body Parameter

Parameter Type Description
broadcaster_id string The broadcaster running polls. Provided broadcaster_id must match the user_id in the user OAuth token.

Maximum: 1
id string ID of the poll.
status string The poll status to be set. Valid values:

TERMINATED: End the poll manually, but allow it to be viewed publicly.

ARCHIVED: End the poll manually and do not allow it to be viewed publicly.

Return Values

Parameter Type Description
id string ID of the poll.
broadcaster_id string ID of the broadcaster.
broadcaster_name string Name of the broadcaster.
broadcaster_login string Login of the broadcaster.
title string Question displayed for the poll.
choices object[] Array of the poll choices.
choice.id string ID for the choice.
choice.title string Text displayed for the choice.
choice.votes integer Total number of votes received for the choice.
choice.channel_points_votes integer Number of votes received via Channel Points.
choice.bits_votes integer Number of votes received via Bits.
bits_voting_enabled boolean Indicates if Bits can be used for voting.
bits_per_vote integer Number of Bits required to vote once with Bits.
channel_points_voting_enabled boolean Indicates if Channel Points can be used for voting.
channel_points_per_vote integer Number of Channel Points required to vote once with Channel Points.
status string Poll Status. Valid values are:

ACTIVE: Poll is currently in progress.

COMPLETED: Poll has reached its ended_at time.

TERMINATED: Poll has been manually terminated before its ended_at time.

ARCHIVED: Poll is no longer visible on the channel.

MODERATED: Poll is no longer visible to any user on Twitch.

INVALID: Something went wrong determining the state.
duration integer Total duration for the poll (in seconds).
started_at string UTC timestamp for the poll’s start time.
ended_at string UTC timestamp for the poll’s end time.

Response Codes

Code Meaning
200 Poll ended successfully.
400 Request was invalid.
401 Authorization failed.

Example Request

Ends a specific poll for the TwitchDev channel, but allows the results to be visible for viewers.

curl -X POST 'https://api.twitch.tv/helix/polls' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "broadcaster_id":"141981764",
  "id":"ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
  "status":"TERMINATED"
}'

Example Response

{
  "data": [
    {
      "id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Heads or Tails?",
      "choices": [
        {
          "id": "4c123012-1351-4f33-84b7-43856e7a0f47",
          "title": "Heads",
          "votes": 0,
          "channel_points_votes": 0,
          "bits_votes": 0
        },
        {
          "id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
          "title": "Tails",
          "votes": 0,
          "channel_points_votes": 0,
          "bits_votes": 0
        }
      ],
      "bits_voting_enabled": false,
      "bits_per_vote": 0,
      "channel_points_voting_enabled": true,
      "channel_points_per_vote": 100,
      "status": "TERMINATED",
      "duration": 1800,
      "started_at": "2021-03-19T06:08:33.871278372Z",
      "ended_at": "2021-03-19T06:11:26.746889614Z"
    }
  ]
}

Get Predictions

NEW Get information about all Channel Points Predictions or specific Channel Points Predictions for a Twitch channel. Results are ordered by most recent, so it can be assumed that the currently active or locked Prediction will be the first item.

BETA This endpoint is currently available as part of a public beta and should not be used in production environments. See Product Lifecycle for more information regarding the expectations of beta versions.

Authorization

  • User OAuth token
  • Required scope: channel:read:predictions

URL

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

Pagination Support

Forward pagination.

Required Query Parameter

Parameter Type Description
broadcaster_id string The broadcaster running Predictions. Provided broadcaster_id must match the user_id in the user OAuth token.

Maximum: 1

Optional Query Parameter

Parameter Type Description
id string ID of a Prediction. Filters results to one or more specific Predictions. Not providing one or more IDs will return the full list of Predictions for the authenticated channel.

Maximum: 100
after string Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
first string Maximum number of objects to return.

Maximum: 20. Default: 20.

Return Values

Parameter Type Description
id string ID of the Prediction.
broadcaster_id string ID of the broadcaster.
broadcaster_name string Name of the broadcaster.
broadcaster_login string Login of the broadcaster.
title string Title for the Prediction.
winning_outcome_id string ID of the winning outcome. If the status is ACTIVE, this is set to null.
outcomes object[] Array of possible outcomes for the Prediction.
outcome.id string ID for the outcome.
outcome.title string Text displayed for outcome.
outcome.users integer Number of unique uesrs that chose the outcome.
outcome.channel_points integer Number of Channel Points used for the outcome.
outcome.top_predictors object[] Array of users who were the top predictors. null if none.
outcome.top_predictors.user.id string ID of the user.
outcome.top_predictors.user.name string Display name of the user.
outcome.top_predictors.user.login string Login of the user.
outcome.top_predictors.user.channel_points_used integer Number of Channel Points used by the user.
outcome.top_predictors.user.channel_points_won integer Number of Channel Points won by the user.
outcome.color string Color for the outcome. Valid values: BLUE, PINK
prediction_window integer Total duration for the Prediction (in seconds).
status string Status of the Prediction. Valid values are:

RESOLVED: A winning outcome has been chosen and the Channel Points have been distributed to the users who guessed the correct outcome.

ACTIVE: The Prediction is active and viewers can make predictions.

CANCELED: The Prediction has been canceled and the Channel Points have been refunded to participants.

LOCKED: The Prediction has been locked and viewers can no longer make predictions.
created_at string UTC timestamp for the Prediction’s start time.
ended_at string UTC timestamp for when the Prediction ended. If the status is ACTIVE, this is set to null.
locked_at string UTC timestamp for when the Prediction was locked. If the status is not LOCKED, this is set to null.

Response Codes

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

Example Request

Returns information for a specific Prediction created for the TwitchDev channel.

curl -X GET 'https://api.twitch.tv/helix/predictions?broadcaster_id=55696719&id=d6676d5c-c86e-44d2-bfc4-100fb48f0656' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "id": "d6676d5c-c86e-44d2-bfc4-100fb48f0656",
      "broadcaster_id": "55696719",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Will there be any leaks today?",
      "winning_outcome_id": null,
      "outcomes": [
        {
          "id": "021e9234-5893-49b4-982e-cfe9a0aaddd9",
          "title": "Yes",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "BLUE"
        },
        {
          "id": "ded84c26-13cb-4b48-8cb5-5bae3ec3a66e",
          "title": "No",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "PINK"
        }
      ],
      "prediction_window": 600,
      "status": "ACTIVE",
      "created_at": "2021-04-28T16:03:06.320848689Z",
      "ended_at": null,
      "locked_at": null
    }
  ],
  "pagination": {}
}

Create Prediction

NEW Create a Channel Points Prediction for a specific Twitch channel.

BETA This endpoint is currently available as part of a public beta and should not be used in production environments. See Product Lifecycle for more information regarding the expectations of beta versions.

Authorization

  • User OAuth token
  • Required scope: channel:manage:predictions

URL

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

Required Body Parameter

Parameter Type Description
broadcaster_id string The broadcaster running Predictions. Provided broadcaster_id must match the user_id in the user OAuth token.

Maximum: 1
title string Title for the Prediction.

Maximum: 45 characters.
outcomes object[] Array of outcome objects with titles for the Prediction. Array size must be 2. The first outcome object is the “blue” outcome and the second outcome object is the “pink” outcome when viewing the Prediction on Twitch.
outcome.title string Text displayed for the outcome choice.

Maximum: 25 characters.
prediction_window integer Total duration for the Prediction (in seconds).

Minimum: 1. Maximum: 1800.

Return Values

Parameter Type Description
id string ID of the Prediction.
broadcaster_id string ID of the broadcaster.
broadcaster_login string Login of the broadcaster.
broadcaster_name string Name of the broadcaster.
title string Title for the Prediction.
winning_outcome_id string ID of the winning outcome.
outcomes object[] Array of possible outcomes for the Prediction.
outcome.id string ID for the outcome.
outcome.title string Text displayed for outcome.
outcome.users integer Number of unique uesrs that chose the outcome.
outcome.channel_points integer Number of Channel Points used for the outcome.
outcome.color string Color for the outcome. Valid values: BLUE, PINK
outcome.top_predictors object[] Array of users who were the top predictors.
outcome.top_predictors.user.id string ID of the user.
outcome.top_predictors.user.name string Display name of the user.
outcome.top_predictors.user.login string Login of the user.
outcome.top_predictors.user.channel_points_used integer Number of Channel Points used by the user.
outcome.top_predictors.user.channel_points_won integer Number of Channel Points won by the user.
prediction_window integer Total duration for the Prediction (in seconds).
status string Status of the Prediction. Valid values are:

RESOLVED: A winning outcome has been chosen and the Channel Points have been distributed to the users who predicted the correct outcome.

ACTIVE: The Prediction is active and viewers can make predictions.

CANCELED: The Prediction has been canceled and the Channel Points have been refunded to participants.

LOCKED: The Prediction has been locked and viewers can no longer make predictions.
created_at string UTC timestamp for the Prediction’s start time.
ended_at string UTC timestamp for when the Prediction ended. If the status is ACTIVE, this is set to null.
locked_at string UTC timestamp for when the Prediction was locked. If the status is not LOCKED, this is set to null.

Response Codes

Code Meaning
200 Prediction created successfully.
400 Request was invalid.
401 Authorization failed.

Example Request

Creates a Prediction for the TwitchDev channel.

curl -X POST 'https://api.twitch.tv/helix/predictions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{
  "broadcaster_id": "141981764",
  "title": "Any leeks in the stream?",
  "outcomes": [
    {
      "title": "Yes, give it time."
    },
    {
      "title": "Definitely not."
    }
  ],
  "prediction_window": 120,
}'

Example Response

{
  "data": [
    {
      "id": "bc637af0-7766-4525-9308-4112f4cbf178",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Any leeks in the stream?",
      "winning_outcome_id": null,
      "outcomes": [
        {
          "id": "73085848-a94d-4040-9d21-2cb7a89374b7",
          "title": "Yes, give it time.",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "BLUE"
        },
        {
          "id": "906b70ba-1f12-47ea-9e95-e5f93d20e9cc",
          "title": "Definitely not.",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "PINK"
        }
      ],
      "prediction_window": 120,
      "status": "ACTIVE",
      "created_at": "2021-04-28T17:11:22.595914172Z",
      "ended_at": null,
      "locked_at": null
    }
  ]
}

End Prediction

NEW Lock, resolve, or cancel a Channel Points Prediction. Active Predictions can be updated to be “locked,” “resolved,” or “canceled.” Locked Predictions can be updated to be “resolved” or “canceled.”

BETA This endpoint is currently available as part of a public beta and should not be used in production environments. See Product Lifecycle for more information regarding the expectations of beta versions.

Authorization

  • User OAuth token
  • Required scope: channel:manage:predictions

URL

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

Required Body Parameter

Parameter Type Description
broadcaster_id string The broadcaster running prediction events. Provided broadcaster_id must match the user_id in the user OAuth token.

Maximum: 1
id string ID of the Prediction.
status string The Prediction status to be set. Valid values:

RESOLVED: A winning outcome has been chosen and the Channel Points have been distributed to the users who predicted the correct outcome.

CANCELED: The Prediction has been canceled and the Channel Points have been refunded to participants.

LOCKED: The Prediction has been locked and viewers can no longer make predictions.

Optional Body Parameter

Parameter Type Description
winning_outcome_id string ID of the winning outcome for the Prediction. This parameter is required if status is being set to RESOLVED.

Return Values

Parameter Type Description
id string ID of the prediction.
broadcaster_id string ID of the broadcaster.
broadcaster_login string Login of the broadcaster.
broadcaster_name string Name of the broadcaster.
title string Title for the prediction.
winning_outcome_id string ID of the winning outcome.
outcomes object[] Array of possible outcomes for the prediction.
outcome.id string ID for the outcome.
outcome.title string Text displayed for outcome.
outcome.users integer Number of unique uesrs that chose the outcome.
outcome.channel_points integer Number of Channel Points used for the outcome.
outcome.color string Color for the outcome. Valid values: BLUE, PINK
outcome.top_predictors object[] Array of users who were the top predictors.
outcome.top_predictors.user.id string ID of the user.
outcome.top_predictors.user.name string Display name of the user.
outcome.top_predictors.user.login string Login of the user.
outcome.top_predictors.user.channel_points_used integer Number of Channel Points used by the user.
outcome.top_predictors.user.channel_points_won integer Number of Channel Points won by the user.
prediction_window integer Total duration for the prediction (in seconds).
status string Status of the prediction. Valid values are:

RESOLVED: A winning outcome has been chosen and the Channel Points have been distributed to the users who predicted the correct outcome.

ACTIVE: The Prediction is active and viewers can make predictions.

CANCELED: The Prediction has been canceled and the Channel Points have been refunded to participants.

LOCKED: The Prediction has been locked and viewers can no longer make predictions.
created_at string UTC timestamp for the prediction’s start time.
ended_at string UTC timestamp for when the prediction ended. If the status is ACTIVE, this is set to null.
locked_at string UTC timestamp for when the prediction was locked. If the status is not LOCKED, this is set to null.

Response Codes

Code Meaning
200 Prediction ended successfully.
400 Request was invalid.
401 Authorization failed.

Example Request

Ends a specific Prediction for the TwitchDev channel by setting the status to be resolved.

curl -X PATCH 'https://api.twitch.tv/helix/predictions' \ -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \ -H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \ -H 'Content-Type: application/json' \ -d  '{
  "broadcaster_id": "141981764",
  "id": "bc637af0-7766-4525-9308-4112f4cbf178",
  "status": "RESOLVED",
  "winning_outcome_id": "73085848-a94d-4040-9d21-2cb7a89374b7"
}'

Example Response

{
  "data": [
    {
      "id": "bc637af0-7766-4525-9308-4112f4cbf178",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Will we win all the games?",
      "winning_outcome_id": "73085848-a94d-4040-9d21-2cb7a89374b7",
      "outcomes": [
        {
          "id": "73085848-a94d-4040-9d21-2cb7a89374b7",
          "title": "yes",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "BLUE"
        },
        {
          "id": "86010b2e-9764-4136-9359-fd1c9c5a8033",
          "title": "no",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "PINK"
        }
      ],
      "prediction_window": 120,
      "status": "RESOLVED",
      "created_at": "2021-04-28T21:48:19.480371331Z",
      "ended_at": "2021-04-28T21:54:24.026833954Z",
      "locked_at": "2021-04-28T21:48:34.636685705Z"
    }
  ]
}

Search Categories

Returns a list of games or categories that match the query via name either entirely or partially.

Authentication

OAuth or App Access Token required

URL

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

Pagination Support

Forward pagination only.

Required Query Parameters

Parameter Type Description
query string URl encoded search query

Optional Query Parameters

Paramater Type Description
first integer Maximum number of objects to return.
Maximum: 100.
Default: 20.
after string Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.

Return Values

Parameter Type Description
box_art_url string Template URL for the game’s box art.
name string Game/category name.
id string Game/category ID.

Note: The return values are the same as returned from GET https://api.twitch.tv/helix/games

Example Request

This request queries for games and categories.

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

Example Response

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

Search Channels

Returns a list of channels (users who have streamed within the past 6 months) that match the query via channel name or description either entirely or partially. Results include both live and offline channels. Online channels will have additional metadata (e.g. started_at, tag_ids).

Authentication

OAuth or App Access Token required

Pagination Support

Forward only.

URL

GET helix/search/channels

Required Query Parameters

Parameter Type Description
query string URl encoded search query

Optional Query Parameters

Parameter Type Description
first integer Maximum number of objects to return.
Maximum: 100
Default: 20
after string Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
live_only Boolean Filter results for live streams only.
Default: false

Return Values

Parameter Type Description
broadcaster_language string Channel language
(Broadcaster Language field from the Channels service). A language value is either the ISO 639-1 two-letter code for a supported stream language or “other”.
broadcaster_login string Login of the broadcaster.
display_name string Display name of the broadcaster.
game_id string ID of the game being played on the stream.
game_name string Name of the game being played on the stream.
id string Channel ID.
is_live Boolean Indicates if the channel is currenty live.
tag_ids string[] Tag IDs that apply to the stream. This array only contains strings when a channel is live. For all possibilities, see List of All Tags. Category Tags are not returned.
thumbnail_url string Thumbnail URL of the stream. All image URLs have variable width and height. You can replace {width} and {height} with any values to get that size image.
title string Stream title.
started_at string UTC timestamp. Returns an empty string if the channel is not live.

Example Requests

This example searches for channels:

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

This example searches for live channels:

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

Example Responses

Search for channels response:

{
  "data": [
    {
      "broadcaster_language": "en",
      "broadcaster_login": "loserfruit",
      "display_name": "Loserfruit",
      "game_id": "498000",
      "game_name": "House Flipper",
      "id": "41245072",
      "is_live": false,
      "tags_ids": [],
      "thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/fd17325a-7dc2-46c6-8617-e90ec259501c-profile_image-300x300.png",
      "title": "loserfruit",
      "started_at": ""
    },
... ],
  "pagination": {
    "cursor": "Mg=="
  }
}

Search for live channels response:

{
  "data": [
    {
      "broadcaster_language": "en",
      "broadcaster_login": "a_seagull",
      "display_name": "A_Seagull",
      "game_id": "506442",
      "game_name": "DOOM Eternal",
      "id": "19070311",
      "is_live": true,
      "tags_ids": [
        "6ea6bca4-4712-4ab9-a906-e3336a9d8039"
      ],
      "thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/a_seagull-profile_image-4d2d235688c7dc66-300x300.png",
      "title": "a_seagull",
      "started_at": "2020-03-18T17:56:00Z"
    }
  ],
  "pagination": {}
}

 

Get Stream Key

Gets the channel stream key for a user.

Authentication

  • User OAuth token

  • Required scope: channel:read:stream_key

URL

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

Query Parameters

Parameter Required Type Description
broadcaster_id yes string User ID of the broadcaster

Response Body

Parameter Type  Description
stream_key string Stream key for the channel

Possible Response Codes

HTTP Code Meaning
200 Channel/Stream information returned successfully
401 Authentication failure
500 Internal Server Error, Failed to get channel information

Example Request

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

Example Response

{
  "data": [
    {
      "stream_key": "live_44322889_a34ub37c8ajv98a0"
    },
  ]
}

Get Streams

Gets information about active streams. Streams are returned sorted by number of current viewers, in descending order. Across multiple pages of results, there may be duplicate or missing streams, as viewers join and leave streams.

The response has a JSON payload with a data field containing an array of stream information elements and a pagination field containing information required to query for more streams.

Authentication

OAuth or App Access Token required

URL

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

Required Query Parameters

None

Optional Query Parameters

Name Type Description
after string Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
before string Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
first integer Maximum number of objects to return. Maximum: 100. Default: 20.
game_id string Returns streams broadcasting a specified game ID. You can specify up to 100 IDs.
language string Stream language. You can specify up to 100 languages. A language value must be either the ISO 639-1 two-letter code for a supported stream language or “other”.
user_id string Returns streams broadcast by one or more specified user IDs. You can specify up to 100 IDs.
user_login string Returns streams broadcast by one or more specified user login names. You can specify up to 100 names.

Response Fields

Field Type Description
id string Stream ID.
user_id string ID of the user who is streaming.
user_login string Login of the user who is streaming.
user_name string Display name corresponding to user_id.
game_id string ID of the game being played on the stream.
game_name string Name of the game being played.
type string Stream type: "live" or "" (in case of error).
title string Stream title.
viewer_count int Number of viewers watching the stream at the time of the query.
started_at string UTC timestamp.
language string Stream language. A language value is either the ISO 639-1 two-letter code for a supported stream language or “other”.
thumbnail_url string Thumbnail URL of the stream. All image URLs have variable width and height. You can replace {width} and {height} with any values to get that size image
tag_ids string Shows tag IDs that apply to the stream.
is_mature boolean Indicates if the broadcaster has specified their channel contains mature content that may be inappropriate for younger audiences.
pagination object containing a string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.

Example Request #1

This gets information about the 20 most active streams.

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

Example Response 1

{
  "data": [
    {
      "id": "41375541868",
      "user_id": "459331509",
      "user_login": "auronplay",
      "user_name": "auronplay",
      "game_id": "494131",
      "game_name": "Little Nightmares",
      "type": "live",
      "title": "hablamos y le damos a Little Nightmares 1",
      "viewer_count": 78365,
      "started_at": "2021-03-10T15:04:21Z",
      "language": "es",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_auronplay-{width}x{height}.jpg",
      "tag_ids": [
        "d4bb9c58-2141-4881-bcdc-3fe0505457d1"
      ],
      "is_mature": false
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19"
  }
}

Example Request 2

This gets information about the next 20 most active streams, after the ones specified in the prior response. The request includes as its after value, the cursor returned in the prior response.

curl -X GET
'https://api.twitch.tv/helix/streams?first=20&after=eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response 2

{
  "data": [
    {
      "id": "40944942733",
      "user_id": "67931625",
      "user_login": "amar",
      "user_name": "Amar",
      "game_id": "33214",
      "game_name": "Fortnite",
      "type": "live",
      "title": "27h Stream Pringles Deathrun Map + 12k MK Turnier | !sub !JustLegends !Pc !yfood",
      "viewer_count": 14944,
      "started_at": "2021-03-09T16:59:39Z",
      "language": "de",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_amar-{width}x{height}.jpg",
      "tag_ids": [
        "9166ad14-41f1-4b04-a3b8-c8eb838c6be6"
      ],
      "is_mature": false
    },
  ],
  "pagination": {
    "cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam94TkRrME5DNDFOekV5TXpBMU1UWTVNRElzSW1RaU9tWmhiSE5sTENKMElqcDBjblZsZlE9PSJ9LCJhIjp7IkN1cnNvciI6ImV5SnpJam81TlRFMkxqVTNOREF6TmpNNU9UTXpNaXdpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In19"
  }
}

Example Request 3

This gets information about three different specified streams using the ability to pass multiple logins. If a provided user is not live, they will not be included in the response.

curl -X GET
'https://api.twitch.tv/helix/streams?user_login=afro&user_login=cohhcarnage&user_login=lana_lux' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response 3

{
  "data": [
    {
      "id": "40952121085",
      "user_id": "101051819",
      "user_login": "afro",
      "user_name": "Afro",
      "game_id": "32982",
      "game_name": "Grand Theft Auto V",
      "type": "live",
      "title": "Jacob: Digital Den Laptops & Routers | NoPixel | !MAINGEAR !FCF",
      "viewer_count": 1490,
      "started_at": "2021-03-10T03:18:11Z",
      "language": "en",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_afro-{width}x{height}.jpg",
      "tag_ids": [
        "6ea6bca4-4712-4ab9-a906-e3336a9d8039"
      ],
      "is_mature": false
    },
    ...
  ],
  "pagination": {}
}

Get Followed Streams

Gets information about active streams belonging to channels that the authenticated user follows. Streams are returned sorted by number of current viewers, in descending order. Across multiple pages of results, there may be duplicate or missing streams, as viewers join and leave streams.

Authentication

  • OAuth user token required
  • Required scope: user:read:follows

URL

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

Required Query Parameters

Name Type Description
user_id string Results will only include active streams from the channels that this Twitch user follows. user_id must match the User ID in the bearer token.

Optional Query Parameters

Name Type Description
after string Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
first integer Maximum number of objects to return. Maximum: 100. Default: 100.

Response Fields

Field Type Description
game_id string ID of the game being played on the stream.
game_name string Name of the game being played.
id string Stream ID.
language string Stream language. A language value is either the ISO 639-1 two-letter code for a supported stream language or “other”.
pagination object containing a string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.
started_at string UTC timestamp.
tag_ids string Shows tag IDs that apply to the stream.
thumbnail_url string Thumbnail URL of the stream. All image URLs have variable width and height. You can replace {width} and {height} with any values to get that size image
title string Stream title.
type string Stream type: "live" or "" (in case of error).
user_id string ID of the user who is streaming.
user_login string Login of the user who is streaming.
user_name string Display name corresponding to user_id.
viewer_count int Number of viewers watching the stream at the time of the query.

Example Request

Retrieves the active streams for the channels that the TwitchDev user follows.

curl -X GET 'https://api.twitch.tv/helix/streams/followed?user_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

{
  "data": [
    {
      "id": "42170724654",
      "user_id": "132954738",
      "user_login": "aws",
      "user_name": "AWS",
      "game_id": "417752",
      "game_name": "Talk Shows & Podcasts",
      "type": "live",
      "title": "AWS Howdy Partner! Y'all welcome ExtraHop to the show!",
      "viewer_count": 20,
      "started_at": "2021-03-31T20:57:26Z",
      "language": "en",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_aws-{width}x{height}.jpg",
      "tag_ids": [
        "6ea6bca4-4712-4ab9-a906-e3336a9d8039"
      ]
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19"
  }
}

Create Stream Marker

Creates a marker in the stream of a user specified by user ID. A marker is an arbitrary point in a stream that the broadcaster wants to mark; e.g., to easily return to later. The marker is created at the current timestamp in the live broadcast when the request is processed. Markers can be created by the stream owner or editors. The user creating the marker is identified by a Bearer token.

Markers cannot be created in some cases (an error will occur):

  • If the specified user’s stream is not live.
  • If VOD (past broadcast) storage is not enabled for the stream.
  • For premieres (live, first-viewing events that combine uploaded videos with live chat).
  • For reruns (subsequent (not live) streaming of any past broadcast, including past premieres).

Authentication

  • OAuth token required
  • Required scope: channel:manage:broadcast

URL

POST https://api.twitch.tv/helix/streams/markers

Required Query Parameters

None

Optional Query Parameters

None

Required Body Parameter

NameTypeParameter
user_idstring

ID of the broadcaster in whose live stream the marker is created.

Optional Body Parameter

NameTypeParameter
descriptionstringDescription of or comments on the marker. Max length is 140 characters.

Response Fields

FieldTypeDescription
created_atstringRFC3339 timestamp of the marker.
descriptionstringDescription of the marker.
idstringUnique ID of the marker.
position_secondsintegerRelative offset (in seconds) of the marker, from the beginning of the stream.

Example Request

This creates a marker at the current location in user 123’s stream.

curl -X POST 'https://api.twitch.tv/helix/streams/markers' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{"user_id":"123", "description":"hello, this is a marker!"}'

Example Response

{
  "data": [
     {
        "id": 123,
        "created_at": "2018-08-20T20:10:03Z",
        "description": "hello, this is a marker!",
        "position_seconds": 244
     }
  ]
}

Get Stream Markers

Gets a list of markers for either a specified user’s most recent stream or a specified VOD/video (stream), ordered by recency. A marker is an arbitrary point in a stream that the broadcaster wants to mark; e.g., to easily return to later. The only markers returned are those created by the user identified by the Bearer token.

The response has a JSON payload with a data field containing an array of marker information elements and a pagination field containing information required to query for more follow information.

Authentication

  • OAuth token required
  • Required scope: user:read:broadcast

URL

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

Required Query Parameter

Only one of user_id and video_id must be specified.

NameTypeDescription
user_idstringID of the broadcaster from whose stream markers are returned.
video_idstring

ID of the VOD/video whose stream markers are returned.

Optional Query Parameters

NameTypeDescription
afterstringCursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
beforestringCursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
firststring

Number of values to be returned when getting videos by user or game ID. Limit: 100. Default: 20.

Response Fields

FieldTypeDescription
idstringID of the marker.
created_atstringRFC3339 timestamp of the marker.
descriptionstringDescription of the marker.
paginationobject containing a stringA cursor value, to be used in a subsequent request to specify the starting point of the next set of results. If this is empty, you are at the last page.
position_secondsintegerRelative offset (in seconds) of the marker, from the beginning of the stream.
URLstringA link to the stream with a query parameter that is a timestamp of the marker's location.
user_idstringID of the user whose markers are returned.
user_namestringDisplay name corresponding to user_id.
user_loginstringLogin corresponding to user_id.
video_idstringID of the stream (VOD/video) that was marked.

Example Request

This returns the first 5 markers in the most recent stream of user 123.

curl -X GET 'https://api.twitch.tv/helix/streams/markers?user_id=123&first=5' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    {
      "user_id": "123",
      "user_name": "TwitchName",
      "user_login": "twitchname",
      "videos": [
        {
          "video_id": "456",
          "markers": [
            {
              "id": "106b8d6243a4f883d25ad75e6cdffdc4",
              "created_at": "2018-08-20T20:10:03Z",
              "description": "hello, this is a marker!",
              "position_seconds": 244,
              "URL": "https://twitch.tv/videos/456?t=0h4m06s"
            },
            ...
          ]
        }
      ]
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjoiMjk1MjA0Mzk3OjI1Mzpib29rbWFyazoxMDZiOGQ1Y"
  }
}

Get Broadcaster Subscriptions

Description

Get all of the subscriptions for a specific broadcaster.

Authentication

  • OAuth token required
  • Required scope: channel:read:subscriptions

Subscriptions can be requested on behalf of a broadcaster with a user access token or by a Twitch Extension with an app access token if the broadcaster has granted the channel:read:subscriptions scope from within the Twitch Extensions manager.

Pagination support

Forward only

URL

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

Required Query Parameter

Parameter Type Description
broadcaster_id string User ID of the broadcaster. Must match the User ID in the Bearer token.

Optional Query Parameter

Parameter Type Description
user_id string Filters results to only include potential subscriptions made by the provided user IDs. Accepts up to 100 values.
after string Cursor for forward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without user_id. If a user_id is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query.
first string Maximum number of objects to return. Maximum: 100. Default: 20.

Return Values

Parameter Type Description
broadcaster_id string User ID of the broadcaster.
broadcaster_login string Login of the broadcaster.
broadcaster_name string Display name of the broadcaster.
gifter_id string If the subscription was gifted, this is the user ID of the gifter. Empty string otherwise.
gifter_login string If the subscription was gifted, this is the login of the gifter. Empty string otherwise.
gifter_name string If the subscription was gifted, this is the display name of the gifter. Empty string otherwise.
is_gift Boolean true if the subscription is a gift subscription.
plan_name string Name of the subscription.
tier string Type of subscription (Tier 1, Tier 2, Tier 3).
1000 = Tier 1, 2000 = Tier 2, 3000 = Tier 3 subscriptions.
user_id string ID of the subscribed user.
user_name string Display name of the subscribed user.
user_login string Login of the subscribed user.
pagination object containing a string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. If this is empty, you are at the last page.

Example Request

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

Example Response

{
  "data": [
    {
      "broadcaster_id": "141981764",
      "broadcaster_login": "twitchdev",
      "broadcaster_name": "TwitchDev",
      "gifter_id": "12826",
      "gifter_login": "twitch",
      "gifter_name": "Twitch",
      "is_gift": true,
      "tier": "1000",
      "plan_name": "Channel Subscription (twitchdev)",
      "user_id": "527115020",
      "user_name": "twitchgaming",
      "user_login": "twitchgaming"
    },
    ...
  ],
  "pagination": {
    "cursor": "xxxx"
  }
}

Check User Subscription

Checks if a specific user (user_id) is subscribed to a specific channel (broadcaster_id).

Authentication

  • User access token with scope user:read:subscriptions
  • App access token if the user has authorized your application with scope user:read:subscriptions

URL

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

Required Query Parameters

Parameter Type Description
broadcaster_id string User ID of an Affiliate or Partner broadcaster.
user_id string User ID of a Twitch viewer.

Response Fields

Field Type Description
broadcaster_id string User ID of the broadcaster.
broadcaster_login string Login of the broadcaster.
broadcaster_name string Display name of the broadcaster.
is_gift boolean Indicates if the subscription is a gift.
gifter_login string Login of the gifter (if is_gift is true).
gifter_name string Display name of the gifter (if is_gift is true).
tier string Subscription tier. 1000 is tier 1, 2000 is tier 2, and 3000 is tier 3.

Response Codes

Code Meaning
200 User subscription returned successfully.
400 Request was invalid.
401 Authorization failed.
404 User not subscribed to the channel.

Example Request

Checks if the user TwitchDev (141981764) subscribes to the TwitchPresents (149747285) channel.

curl -X GET 'https://api.twitch.tv/helix/subscriptions/user?broadcaster_id=149747285&user_id=141981764' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response #1

If TwitchDev does subscribe to the TwitchPresents channel.

{
  "data": [
    {
      "broadcaster_id": "149747285",
      "broadcaster_name": "TwitchPresents",
      "broadcaster_login": "twitchpresents",
      "is_gift": false,
      "tier": "1000"
    }
  ]
}

Example Response #2

If TwitchDev does not subscribe to the TwitchPresents channel.

{
  "error": "Not Found",
  "message": "twitchdev has no subscription to twitchpresents",
  "status": 404
}

Get All Stream Tags

Gets the list of all stream tags defined by Twitch, optionally filtered by tag ID(s).

The response has a JSON payload with a data field containing an array of tag elements and a pagination field containing information required to query for more tags.

Authentication

App access token

URL

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

Required Query Parameters

None

Optional Query Parameters

Name Type Description
after string Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
first integer Maximum number of objects to return. Maximum: 100. Default: 20.
tag_id string ID of a tag. Multiple IDs can be specified, separated by ampersands. If provided, only the specified tag(s) is(are) returned.

Maximum of 100.

Response Fields

Field Type Description
tag_id string ID of the tag.
is_auto Boolean true if the tag is auto-generated; otherwise, false . An auto-generated tag is one automatically applied by Twitch (e.g., a language tag based on the broadcaster’s settings); these tags cannot be added or removed by the user.
localization_names map[string]string All localized names of the tag.
localization_descriptions map[string]string All localized descriptions of the tag.
pagination object containing a string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.
Not supported when tag_id is provided.

 

Example Request

This gets the first page of stream tags defined by Twitch.

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

Example Response

{
  "data": [
    {
      "tag_id": "621fb5bf-5498-4d8f-b4ac-db4d40d401bf",
      "is_auto": false,
      "localization_names": {
        "bg-bg": "Изчистване на 1 кредит",
        "cs-cz": "1 čistý kredit",
        "da-dk": "1 credit klaret",
        "de-de": "Mit 1 Leben abschließen",
        "el-gr": "1 μόνο πίστωση",
        "en-us": "1 Credit Clear",
        ...
      },
      "localization_descriptions": {
        "bg-bg": "За потоци с акцент върху завършване на аркадна игра с монети, в която не се използва продължаване",
        "cs-cz": "Pro vysílání s důrazem na plnění mincových arkádových her bez použití pokračování.",
        "da-dk": "Til streams med vægt på at gennemføre et arkadespil uden at bruge continues",
        "de-de": "Für Streams mit dem Ziel, ein Coin-op-Arcade-Game mit nur einem Leben abzuschließen.",
        "el-gr": "Για μεταδόσεις με έμφαση στην ολοκλήρωση παλαιού τύπου ηλεκτρονικών παιχνιδιών που λειτουργούν με κέρμα, χωρίς να χρησιμοποιούν συνέχειες",
        "en-us": "For streams with an emphasis on completing a coin-op arcade game without using any continues",
        ...
      }
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiI..."
  }
}

Get Stream Tags

Gets the list of current stream tags that have been set for a channel.

Authentication

OAuth Token required.

URL

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

Required Query Parameters

Name Type Description
broadcaster_id string User ID of the channel to get tags.

Optional Query Parameters

None

Response Fields

Field Type Description
tag_id string ID of the tag.
is_auto Boolean true if the tag is auto-generated; otherwise, false . An auto-generated tag is one automatically applied by Twitch (e.g., a language tag based on the broadcaster’s settings); tags these cannot be added or removed by the user.
localization_names map[string]string All localized names of the tag.
localization_descriptions map[string]string All localized descriptions of the tag.

Example Request

This gets the tags for the TwitchGaming channel.

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

Example Response

{
  "data": [
    {
      "tag_id": "6ea6bca4-4712-4ab9-a906-e3336a9d8039",
      "is_auto": true,
      "localization_names": {
        "bg-bg": "английски",
        "cs-cz": "Angličtina",
        "da-dk": "Engelsk",
        "de-de": "Englisch",
        "el-gr": "Αγγλικά",
        "en-us": "English",
        ...
      },
      "localization_descriptions": {
        "bg-bg": "За потоци с използване на английски",
        "cs-cz": "Pro vysílání obsahující angličtinu.",
        "da-dk": "Til streams, hvori der indgår engelsk",
        "de-de": "Für Streams auf Englisch.",
        "el-gr": "Για μεταδόσεις που περιλαμβάνουν τη χρήση Αγγλικών",
        "en-us": "For streams featuring the use of English",
        ...
      }
    }
  ]
}

Replace Stream Tags

Applies specified tags to a specified stream, overwriting any existing tags applied to that stream. If no tags are specified, all tags previously applied to the stream are removed. Automated tags are not affected by this operation.

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

Authentication

  • OAuth token required
  • Required scope: channel:manage:broadcast

URL

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

Required Query Parameters

Name Type Description
broadcaster_id string ID of the stream for which tags are to be replaced.

Optional Query Parameters

None

Optional Body Parameter

Up to five tags can be applied to a stream. If no tag_ids is provided, all tags are removed from the stream.

Name Type Description
tag_ids string [] IDs of tags to be applied to the stream.

Example Request

This adds tags to broadcaster 257788195’s stream.

curl -X PUT 'https://api.twitch.tv/helix/streams/tags?broadcaster_id=257788195' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Content-Type: application/json' \
-d '{"tag_ids":["621fb5bf-5498-4d8f-b4ac-db4d40d401bf","79977fb9-f106-4a87-a386-f1b0f99783dd"]}'

Example Response

204: No Content

Get Channel Teams

Retrieves a list of Twitch Teams of which the specified channel/broadcaster is a member.

Authentication

  • User OAuth Token or App Access Token

URL

GET https://api.twitch.tv/helix/teams/channel

Required Query Parameters

Parameter Type Description
broadcaster_id string User ID for a Twitch user.

Response Fields

Field Type Description
broadcaster_id string User ID of the broadcaster.
broadcaster_login string Login of the broadcaster.
broadcaster_name string Display name of the broadcaster.
background_image_url string URL for the Team background image.
banner string URL for the Team banner.
created_at string Date and time the Team was created.
updated_at string Date and time the Team was last updated.
info string Team description.
thumbnail_url string Image URL for the Team logo.
team_name string Team name.
team_display_name string Team display name.
id string Team ID.

Response Codes

Code Meaning
200 List of Channel Teams returned successfully.
400 Request was invalid.
401 Authorization failed.

Example Request

Retrieves a list of Twitch Teams that the broadcaster CSharpFritz belongs to.

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

Example Response

{
  "data": [
    {
      "broadcaster_id": "96909659",
      "broadcaster_name": "CSharpFritz",
      "broadcaster_login": "csharpfritz",
      "background_image_url": null,
      "banner": null,
      "created_at": "2019-02-11T12:09:22Z",
      "updated_at": "2020-11-18T15:56:41Z",
      "info": "<p>An outgoing and enthusiastic group of friendly channels that write code, teach about technology, and promote the technical community.</p>",
      "thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/team-livecoders-team_logo_image-bf1d9a87ca81432687de60e24ad9593d-600x600.png",
      "team_name": "livecoders",
      "team_display_name": "Live Coders",
      "id": "6358"
    }
  ]
}

Get Teams

Gets information for a specific Twitch Team.

Authentication

  • User OAuth Token or App Access Token

URL

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

Required Query Parameters

One of the two optional query parameters must be specified to return Team information.

Optional Query Parameters

Parameter Type Description
name string Team name.
id string Team ID.

Response Fields

Field Type Description
users Array of user objects Users in the specified Team.
users.user_id string User ID of a Team member.
users.user_login string Login of a Team member.
users.user_name string Display name of a Team member.
background_image_url string URL of the Team background image.
banner string URL for the Team banner.
created_at string Date and time the Team was created.
updated_at string Date and time the Team was last updated.
info string Team description.
thumbnail_url string Image URL for the Team logo.
team_name string Team name.
team_display_name string Team display name.
id string Team ID.

Response Codes

Code Meaning
200 Team information returned successfully.
400 Request was invalid.
401 Authorization failed.

Example Request

This example gets Team information for the Live Coders Team.

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

Example Response

{
  "data": [
    {
      "users": [
        {
          "user_id": "278217731",
          "user_name": "mastermndio",
          "user_login": "mastermndio"
        },
        {
          "user_id": "41284990",
          "user_name": "jenninexus",
          "user_login": "jenninexus"
        },
        ...
      ],
      "background_image_url": null,
      "banner": null,
      "created_at": "2019-02-11T12:09:22Z",
      "updated_at": "2020-11-18T15:56:41Z",
      "info": "<p>An outgoing and enthusiastic group of friendly channels that write code, teach about technology, and promote the technical community.</p>",
      "thumbnail_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/team-livecoders-team_logo_image-bf1d9a87ca81432687de60e24ad9593d-600x600.png",
      "team_name": "livecoders",
      "team_display_name": "Live Coders",
      "id": "6358"
    }
  ]
}

Get Users

Gets information about one or more specified Twitch users. Users are identified by optional user IDs and/or login name. If neither a user ID nor a login name is specified, the user is looked up by Bearer token.

The response has a JSON payload with a data field containing an array of user-information elements.

Authentication

  • OAuth or App Access Token required.

Authorization

  • OAuth token with user:read:email scope required to include the user’s verified email address in response.

URL

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

Required Query Parameters

None

Optional Query Parameters

Name Type Description
id string User ID. Multiple user IDs can be specified. Limit: 100.
login string User login name. Multiple login names can be specified. Limit: 100.

Note: The limit of 100 IDs and login names is the total limit. You can request, for example, 50 of each or 100 of one of them. You cannot request 100 of both.

A request can include a mixture of login names and user ID. If specifying multiple values (any combination of id and/or login values), separate them with ampersands; e.g.,
GET https://api.twitch.tv/helix/users?login=<login name>&id=<user ID>...
GET https://api.twitch.tv/helix/users?id=<user ID>&id=<user ID>...
GET https://api.twitch.tv/helix/users?login=<login name>&login=<login name>...

Response Fields

Field Type Description
broadcaster_type string User’s broadcaster type: "partner", "affiliate", or "".
description string User’s channel description.
display_name string User’s display name.
id string User’s ID.
login string User’s login name.
offline_image_url string URL of the user’s offline image.
profile_image_url string URL of the user’s profile image.
type string User’s type: "staff", "admin", "global_mod", or "".
view_count integer Total number of views of the user’s channel.
email string User’s verified email address. Returned if the request includes the user:read:email scope.
created_at string Date when the user was created.

Example Request

This gets information about user 141981764.

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

Example Response

{
  "data": [
    {
      "id": "141981764",
      "login": "twitchdev",
      "display_name": "TwitchDev",
      "type": "",
      "broadcaster_type": "partner",
      "description": "Supporting third-party developers building Twitch integrations from chatbots to game integrations.",
      "profile_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/8a6381c7-d0c0-4576-b179-38bd5ce1d6af-profile_image-300x300.png",
      "offline_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/3f13ab61-ec78-4fe6-8481-8682cb3b0ac2-channel_offline_image-1920x1080.png",
      "view_count": 5980557,
      "email": "not-real@email.com",
      "created_at": "2016-12-14T20:32:28.894263Z"
    }
  ]
}

Update User

Updates the description of a user specified by the bearer token. Note that the description parameter is optional should other updatable parameters become available in the future. If the description parameter is not provided, no update will occur and the current user data is returned.

Authentication

  • OAuth token required

  • Required scope: user:edit

URL

PUT https://api.twitch.tv/helix/users?description=<description>

Required Query Parameters

None

Optional Query Parameters

Parameter Type Description
description string User’s account description

Response Fields

Response fields are the same as for Get Users. Email is only returned if the user:read:email is also provided.

Example Request

This updates the description of the user specified by Bearer token cfabdegwdoklmawdzdo98xt2fo512y.

curl  -X PUT 'https://api.twitch.tv/helix/users?description=BaldAngel' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data":[{
    "id": "44322889",
    "login": "dallas",
    "display_name": "dallas",
    "type": "staff",
    "broadcaster_type": "affiliate",
    "description": "BaldAngel",
    "profile_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/4d1f36cbf1f0072d-profile_image-300x300.png",
    "offline_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-channel_offline_image-2e82c1df2a464df7-1920x1080.jpeg",
    "view_count": 6995,
    "email": "not-real@email.com",
    "created_at": "2013-06-03T19:12:02.580593Z"
  }]
}

Get Users Follows

Gets information on follow relationships between two Twitch users. This can return information like “who is qotrok following,” “who is following qotrok,” or “is user X following user Y.” Information returned is sorted in order, most recent follow first.

The response has a JSON payload with a data field containing an array of follow relationship elements and a pagination field containing information required to query for more follow information.

Authentication

User OAuth Token or App Access Token

URLs

GET https://api.twitch.tv/helix/users/follows?from_id=<user ID>
GET https://api.twitch.tv/helix/users/follows?to_id=<user ID>

At minimum, from_id or to_id must be provided for a query to be valid.

Required Query Parameters

None

Optional Query Paramaters

Name Type Description
after string Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
first integer Maximum number of objects to return. Maximum: 100. Default: 20.
from_id string User ID. The request returns information about users who are being followed by the from_id user.
to_id string User ID. The request returns information about users who are following the to_id user.

Response Fields

FieldTypeDescription
followed_atstringDate and time when the from_id user followed the to_id user.
from_idstringID of the user following the to_id user.
from_loginstringLogin of the user following the to_id user.
from_namestringDisplay name corresponding to from_id.
paginationobject containing a stringA cursor value, to be used in a subsequent request to specify the starting point of the next set of results.
to_idstringID of the user being followed by the from_id user.
to_loginstringLogin of the user being followed by the from_id user.
to_namestringDisplay name corresponding to to_id.
totalintTotal number of items returned.
  • If only from_id was in the request, this is the total number of followed users.
  • If only to_id was in the request, this is the total number of followers.
  • If both from_id and to_id were in the request, this is 1 (if the "from" user follows the "to" user) or 0.

Example Request

This gets the first 20 IDs of users who are following user 23161357.

curl -X GET 'https://api.twitch.tv/helix/users/follows?to_id=23161357' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
   "total": 12345,
   "data":
   [
      {
         "from_id": "171003792",
         "from_login": "iiisutha067iii",
         "from_name": "IIIsutha067III",
         "to_id": "23161357",
         "to_name": "LIRIK",
         "followed_at": "2017-08-22T22:55:24Z"
      },
      {
         "from_id": "113627897",
         "from_login": "birdman616",
         "from_name": "Birdman616",
         "to_id": "23161357",
         "to_name": "LIRIK",
         "followed_at": "2017-08-22T22:55:04Z"
      },
      ...
   ],
   "pagination":{
     "cursor": "eyJiIjpudWxsLCJhIjoiMTUwMzQ0MTc3NjQyNDQyMjAwMCJ9"
   }
}

Create User Follows

Adds a specified user to the followers of a specified channel.

Authentication

  • OAuth Token required
  • Required scope: user:edit:follows

URL

POST https://api.twitch.tv/helix/users/follows 

Required Query Parameters

Parameter Type Description
from_id string User ID of the follower
to_id string ID of the channel to be followed by the user

Optional Query Parameters

Parameter Type Description
allow_notifications Boolean If true, the user gets email or push notifications (depending on the user’s notification settings) when the channel goes live. Default value is false.

Response Codes

Code Meaning
204 Successfully created follows
400 Missing Query Parameter
422 Entity cannot be processed

Example Request

This example creates a user follow.

curl -X POST 'https://api.twitch.tv/helix/users/follows' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
--data-raw '{"to_id": "41245072","from_id": "57059344"}'

Example Response

204 No content

 

Delete User Follows

Deletes a specified user from the followers of a specified channel.

Authentication

  • OAuth Token required

  • Required scope: user:edit:follows

URL

DELETE https://api.twitch.tv/helix/users/follows

Required Query Parameters

Parameter Type Description
from_id string User ID of the follower
to_id string Channel to be unfollowed by the user

Optional Query Parameters

None

Response Codes

Code Meaning
204 User successfully deleted from list of channel followers
400 Missing Query Parameter
422 Entity cannot be processed

Example Request

This request deletes a user from the followers of a channel.

curl -X DELETE 'https://api.twitch.tv/helix/users/follows?from_id=57059344&to_id=41245072' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz'

Example Response

204 No content

 

Get User Block List

Gets a specified user’s block list. The list is sorted by when the block occurred in descending order (i.e. most recent block first).

Authentication

  • OAuth user token required
  • Required scope: user:read:blocked_users

URL

GET https://api.twitch.tv/helix/users/blocks

Required Query Parameters

Parameter Type Description
broadcaster_id string User ID for a Twitch user.

Optional Query Parameters

Parameter Type Description
first integer Maximum number of objects to return. Maximum: 100. Default: 20.
after string Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.

Response Fields

Field Type Description
user_id string User ID of the blocked user.
user_login string Login of the blocked user.
display_name string Display name of the blocked user.

Response Codes

Code Meaning
200 User’s block list returned successfully.
400 Request was invalid.
401 Authorization failed.

Example Request

This example gets a list of users blocked by the specified user.

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

Example Response

{
  "data": [
    {
      "user_id": "135093069",
      "user_login": "bluelava",
      "display_name": "BlueLava"
    },
    {
      "user_id": "27419011",
      "user_login": "travistyoj",
      "display_name": "TravistyOJ"
    }
  ]
}

Block User

Blocks the specified user on behalf of the authenticated user.

Authentication

  • OAuth user token required
  • Required scope: user:manage:blocked_users

URL

PUT https://api.twitch.tv/helix/users/blocks

Required Query Parameters

Parameter Type Description
target_user_id string User ID of the user to be blocked.

Optional Query Parameters

Parameter Type Description
source_context string Source context for blocking the user. Valid values: "chat", "whisper".
reason string Reason for blocking the user. Valid values: "spam", "harassment", or "other".

Response Codes

Code Meaning
204 User blocked successfully.
400 Request was invalid.
401 Authorization failed.

Example Request

This example blocks a user with an ID of 198704263 on behalf of the authenticated user.

curl -X PUT 'https://api.twitch.tv/helix/users/blocks?target_user_id=198704263' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \

Example Response

204 No Content

Unblock User

Unblocks the specified user on behalf of the authenticated user.

Authentication

  • OAuth user token required
  • Required scope: user:manage:blocked_users

URL

DELETE https://api.twitch.tv/helix/users/blocks

Required Query Parameters

Parameter Type Description
target_user_id string User ID of the user to be unblocked.

Optional Query Parameters

None.

Response Codes

Code Meaning
204 User unblocked successfully.
400 Request was invalid.
401 Authorization failed.

Example Request

This example unblocks a user with an ID of 198704263 on behalf of the authenticated user.

curl -X DELETE 'https://api.twitch.tv/helix/users/blocks?target_user_id=198704263' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \

Example Response

204 No Content

Get User Extensions

Gets a list of all extensions (both active and inactive) for a specified user, identified by a Bearer token.

The response has a JSON payload with a data field containing an array of user-information elements.

Authentication

  • OAuth token required
  • Required scope: user:read:broadcast

URL

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

Required Query Parameters

None

Optional Query Parameters

None

Response Fields

FieldTypeDescription
can_activatebooleanIndicates whether the extension is configured such that it can be activated.
idstringID of the extension.
namestringName of the extension.
typestring arrayTypes for which the extension can be activated. Valid values: "component", "mobile", "panel", "overlay".
versionstringVersion of the extension.

Example Request

This gets installed extensions for the user identified by Bearer token cfabdegwdoklmawdzdo98xt2fo512y.

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

Example Response

{
  "data": [
    {
      "id": "wi08ebtatdc7oj83wtl9uxwz807l8b",
      "version": "1.1.8",
      "name": "Streamlabs Leaderboard",
      "can_activate": true,
      "type": [
        "panel"
      ]
    },
    {
      "id": "d4uvtfdr04uq6raoenvj7m86gdk16v",
      "version": "2.0.2",
      "name": "Prime Subscription and Loot Reminder",
      "can_activate": true,
      "type": [
        "overlay"
      ]
    },
    {
      "id": "rh6jq1q334hqc2rr1qlzqbvwlfl3x0",
       "version": "1.1.0",
      "name": "TopClip",
      "can_activate": true,
      "type": [
        "mobile",
        "panel"
      ]
    },
    {
      "id": "zfh2irvx2jb4s60f02jq0ajm8vwgka",
      "version": "1.0.19",
      "name": "Streamlabs",
      "can_activate": true,
      "type": [
        "mobile",
        "overlay"
      ]
    },
    {
      "id": "lqnf3zxk0rv0g7gq92mtmnirjz2cjj",
      "version": "0.0.1",
      "name": "Dev Experience Test",
      "can_activate": true,
      "type": [
        "component",
        "mobile",
        "panel",
        "overlay"
      ]
    }
  ]
}

Get User Active Extensions

Gets information about active extensions installed by a specified user, identified by a user ID or Bearer token.

Authentication

  • OAuth token required
  • Optional scope: user:read:broadcast or user:edit:broadcast

URL

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

Required Query Parameters

None

Optional Query Parameter

NameTypeDescription
user_idstring

ID of the user whose installed extensions will be returned. Limit: 1.

Response Fields

FieldTypeDescription
activebooleanActivation state of the extension, for each extension type (component, overlay, mobile, panel). If false, no other data is provided.
componentmapContains data for video-component Extensions.
idstringID of the extension.
namestringName of the extension.
overlaymapContains data for video-overlay Extensions.
panelmapContains data for panel Extensions.
versionstringVersion of the extension.
xint(Video-component Extensions only) X-coordinate of the placement of the extension.
yint(Video-component Extensions only) Y-coordinate of the placement of the extension.

Example Request

This updates the description of the user specified by Bearer token cfabdegwdoklmawdzdo98xt2fo512y.

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

Example Response

{
  "data": {
    "panel": {
      "1": {
        "active": true,
        "id": "rh6jq1q334hqc2rr1qlzqbvwlfl3x0",
        "version": "1.1.0",
        "name": "TopClip"
      },
      "2": {
        "active": true,
        "id": "wi08ebtatdc7oj83wtl9uxwz807l8b",
        "version": "1.1.8",
        "name": "Streamlabs Leaderboard"
      },
      "3": {
        "active": true,
        "id": "naty2zwfp7vecaivuve8ef1hohh6bo",
        "version": "1.0.9",
        "name": "Streamlabs Stream Schedule & Countdown"
      }
    },
    "overlay": {
      "1": {
        "active": true,
        "id": "zfh2irvx2jb4s60f02jq0ajm8vwgka",
        "version": "1.0.19",
        "name": "Streamlabs"
      }
    },
    "component": {
      "1": {
        "active": true,
        "id": "lqnf3zxk0rv0g7gq92mtmnirjz2cjj",
        "version": "0.0.1",
        "name": "Dev Experience Test",
        "x": 0,
        "y": 0
      },
      "2": {
        "active": false
      }
    }
  }
}

Update User Extensions

Updates the activation state, extension ID, and/or version number of installed extensions for a specified user, identified by a Bearer token. If you try to activate a given extension under multiple extension types, the last write wins (and there is no guarantee of write order).

Authentication

  • OAuth token required
  • Required scope: user:edit:broadcast

URL

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

Required Query Parameters

None

Optional Query Parameters

None

Response Fields

Response fields are the same as for Get User Active Extensions.

Example Request

This updates the installed extensions of the user specified by Bearer token cfabdegwdoklmawdzdo98xt2fo512y.

curl -X PUT 'https://api.twitch.tv/helix/users/extensions' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H "Content-Type: application/json" \
-d '{
  "data": {
    "panel": {
      "1": {
        "active": true,
        "id": "rh6jq1q334hqc2rr1qlzqbvwlfl3x0",
        "version": "1.1.0"
      },
      "2": {
        "active": true,
        "id": "wi08ebtatdc7oj83wtl9uxwz807l8b",
        "version": "1.1.8"
      },
      "3": {
        "active": true,
        "id": "naty2zwfp7vecaivuve8ef1hohh6bo",
        "version": "1.0.9"
      }
    },
    "overlay": {
      "1": {
        "active": true,
        "id": "zfh2irvx2jb4s60f02jq0ajm8vwgka",
        "version": "1.0.19"
      }
    },
    "component": {
      "1": {
        "active": true,
        "id": "lqnf3zxk0rv0g7gq92mtmnirjz2cjj",
        "version": "0.0.1",
        "x": 0,
        "y": 0
      },
      "2": {
        "active": false
      }
    }
  }
}'

Example Response

{
  "data": {
    "panel": {
      "1": {
        "active": true,
        "id": "rh6jq1q334hqc2rr1qlzqbvwlfl3x0",
        "version": "1.1.0",
        "name": "TopClip"
      },
      "2": {
        "active": true,
        "id": "wi08ebtatdc7oj83wtl9uxwz807l8b",
        "version": "1.1.8",
        "name": "Streamlabs Leaderboard"
      },
      "3": {
        "active": true,
        "id": "naty2zwfp7vecaivuve8ef1hohh6bo",
        "version": "1.0.9",
        "name": "Streamlabs Stream Schedule & Countdown"
      }
    },
    "overlay": {
      "1": {
        "active": true,
        "id": "zfh2irvx2jb4s60f02jq0ajm8vwgka",
        "version": "1.0.19",
        "name": "Streamlabs"
      }
    },
    "component": {
      "1": {
        "active": true,
        "id": "lqnf3zxk0rv0g7gq92mtmnirjz2cjj",
        "version": "0.0.1",
        "name": "Dev Experience Test",
        "x": 0,
        "y": 0
      },
      "2": {
        "active": false
      }
    }
  }
}

Get Videos

Gets video information by video ID (one or more), user ID (one only), or game ID (one only).

The response has a JSON payload with a data field containing an array of video elements. For lookup by user or game, pagination is available, along with several filters that can be specified as query parameters.

Authentication

User OAuth Token or App Access Token

URL

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

Required Query Parameters

Each request must specify one or more video ids, one user_id, or one game_id.

Name Type Description
id string ID of the video being queried. Limit: 100. If this is specified, you cannot use any of the optional query parameters below.
user_id string ID of the user who owns the video. Limit 1.
game_id string ID of the game the video is of. Limit 1.

Optional Query Parameters

These can be used if the request specifies a user_id or game_id, not a video id.

Name Type Description
after string Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
before string Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
first string Number of values to be returned when getting videos by user or game ID. Limit: 100. Default: 20.
language string Language of the video being queried. Limit: 1. A language value must be either the ISO 639-1 two-letter code for a supported stream language or “other”.
period string Period during which the video was created. Valid values: "all", "day", "week", "month". Default: "all".
sort string Sort order of the videos. Valid values: "time", "trending", "views". Default: "time".
type string Type of video. Valid values: "all", "upload", "archive", "highlight". Default: "all".

Response Fields

Fields Type Description
id string ID of the video.
stream_id string ID of the stream that the video originated from if the type is "archive". Otherwise set to null.
user_id string ID of the user who owns the video.
user_login string Login of the user who owns the video.
user_name string Display name corresponding to user_id.
title string Title of the video.
description string Description of the video.
created_at string Date when the video was created.
published_at string Date when the video was published.
url object URL of the video.
thumbnail_url object Template URL for the thumbnail of the video.
viewable string Indicates whether the video is publicly viewable. Valid values: "public", "private".
view_count int Number of times the video has been viewed.
language string Language of the video. A language value is either the ISO 639-1 two-letter code for a supported stream language or “other”.
type string Type of video. Valid values: "upload", "archive", "highlight".
duration string Length of the video.
muted_segments object[] Array of muted segments in the video. If there are no muted segments, the value will be null.
segment.duration integer Duration of the muted segment.
segment.offset integer Offset in the video at which the muted segment begins.
pagination object containing a string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.

Example Request

This gets information about the video with ID 335921245.

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

Example Response

{
  "data": [
    {
      "id": "335921245",
      "stream_id": null,
      "user_id": "141981764",
      "user_login": "twitchdev",
      "user_name": "TwitchDev",
      "title": "Twitch Developers 101",
      "description": "Welcome to Twitch development! Here is a quick overview of our products and information to help you get started.",
      "created_at": "2018-11-14T21:30:18Z",
      "published_at": "2018-11-14T22:04:30Z",
      "url": "https://www.twitch.tv/videos/335921245",
      "thumbnail_url": "https://static-cdn.jtvnw.net/cf_vods/d2nvs31859zcd8/twitchdev/335921245/ce0f3a7f-57a3-4152-bc06-0c6610189fb3/thumb/index-0000000000-%{width}x%{height}.jpg",
      "viewable": "public",
      "view_count": 1863062,
      "language": "en",
      "type": "upload",
      "duration": "3m21s",
      "muted_segments": [
        {
          "duration": 30,
          "offset": 120
        }
      ]
    }
  ],
  "pagination": {}
}

Delete Videos

Deletes one or more videos. Videos are past broadcasts, Highlights, or uploads.

Invalid Video IDs will be ignored (i.e. IDs provided that do not have a video associated with it). If the OAuth user token does not have permission to delete even one of the valid Video IDs, no videos will be deleted and the response will return a 401.

Authentication

  • User OAuth token
  • Required scope: channel:manage:videos

URL

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

Required Query Parameters

Name Type Description
id string ID of the video(s) to be deleted. Limit: 5.

Optional Query Parameters

None.

Response Codes

Code Meaning
200 Video(s) deleted.
400 Request was invalid.
401 Authorization failed; either for the API request itself or if the requester is not authorized to delete the specified videos.

Example Request

This example deletes two videos with the IDs 1234 and 9876.

curl -X DELETE 'https://api.twitch.tv/helix/videos?id=1234&id=9876' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
  "data": [
    "1234",
    "9876"
  ]
}

Get Webhook Subscriptions

Gets the Webhook subscriptions of an application identified by a Bearer token, in order of expiration.

The response has a JSON payload with a data field containing an array of subscription elements and a pagination field containing information required to query for more subscriptions.

Authentication

App access token

URL

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

Required Query Parameters

None

Optional Query Parameters

NameTypeDescription
afterstringCursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. The cursor value specified here is from the pagination response field of a prior query.
firststring

Number of values to be returned per page. Limit: 100. Default: 20.

Response Fields

FieldTypeDescription
callbackstringThe callback provided for this subscription.
expires_atstringDate and time when this subscription expires. Encoded as RFC3339. The timezone is always UTC (“Z”).
paginationobject containing a stringA cursor value, to be used in a subsequent request to specify the starting point of the next set of results. If this is empty, you are at the last page.
topicstringThe topic used in the initial subscription.
totalintA hint at the total number of results returned, on all pages. This is an approximation: as you page through the list, some subscriptions may expire and others may be added.

Example Request

This gets up to 10 webhook subscriptions.

curl -X GET 'https://api.twitch.tv/helix/webhooks/subscriptions?first=10&after=eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IiJ9fQ' \
-H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-H 'Client-Id: uo6dggojyb8d6soh92zknwmi5ej1q2'

Example Response

{
   "total": 12,
   "data": [
       {
           "topic": "https://api.twitch.tv/helix/streams?user_id=123",
           "callback": "http://example.com/your_callback",
           "expires_at": "2018-07-30T20:00:00Z"
       },
       {
           "topic": "https://api.twitch.tv/helix/streams?user_id=345",
           "callback": "http://example.com/your_callback",
           "expires_at": "2018-07-30T20:03:00Z"
       }
   ],
   "pagination": {
       "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IkFYc2laU0k2TVN3aWFTSTZNWDAifX0"
   }
}
+