Contents

Twitch API Reference

Resource Endpoint Description
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. 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.
Bits Get Bits Leaderboard

Gets a ranked list of Bits leaderboard information for an authorized broadcaster.
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.
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).

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.
Entitlements Create Entitlement Grants Upload URL

Creates a URL where you can upload a manifest file and notify users that they have an entitlement. Entitlements are digital items that users are entitled to use. Twitch entitlements are granted to users gratis or as part of a purchase on Twitch.

See the Drops Guide for details about using this endpoint to notify users about Drops.
Entitlements Get Code Status

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 specific code(s). This means that a bits reward can be directly applied without the user having to follow any manual steps (e.g., visiting the Twitch redemption page).

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.
Entitlements Redeem Code

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 specific code(s). This means that a bits reward can be directly applied without the user having to follow any manual steps (e.g., visiting the Twitch redemption page).

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.
Games 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.
Games 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.
Moderation Check AutoMod Status

Determines whether a string message meets the channel’s AutoMod requirements.
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.
Streams 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.
Streams Get Streams Metadata

Gets metadata information about active streams playing Overwatch or Hearthstone. Streams are 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.
Streams Create Stream Marker

Creates a marker in the stream of a user specified by a 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).
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; 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.
Subscriptions Get Broadcaster Subscriptions

Gets all of a broadcaster’s subscriptions
Subscriptions Get Broadcaster's Subscribers

Gets a broadcaster’s subscribers by user ID (one or more).
Subscriptions Get Subscription Events

Returns all subscription events for the past five days.
Tags 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.
Tags Get Stream Tags

Gets the list of tags for a specified stream (channel).
The response has a JSON payload with a data field containing an array of tag elements.
Tags 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.
Users 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.
Users Get Users Follows

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

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.
Users Update User

Updates the description of a user specified by a Bearer token.
Users 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.
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. If you try to activate a given extension under multiple extension types, the last write wins (and there is no guarantee of write order)
Videos 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 string parameters.
Webhooks Get Webhook Subscriptions

Gets the Webhook subscriptions of a user 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.

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

Required scope: analytics:read:extensions

URL

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

Required Query String Parameters

None

Optional Query String 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. Default: January 31, 2018 (overview_v2) or 90 days (overview_v1) before the report was issued. The file contains one row of data per day.
type string Type of analytics report that is returned. If this is specified, the response includes one URL, for the specified report type. If this is not specified, the response includes multiple URLs (paginated), one for each report type available for the authenticated user’s Extensions. Limit: 1. Valid values: "overview_v1", "overview_v2". Default: all report types for the authenticated user’s Extensions.

Response Fields

FieldTypeDescription
ended_atstringReport end date/time.
extension_idstringID of the extension whose analytics data is being provided.
paginationstringA 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 URL for a downloadable CSV of the overview_v1 report for extension ID abcdefg, covering the period March 1, 2018 to May 1, 2018.

curl -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/helix/analytics/extensions?type=overview_v1&extension_id=abcdefgh&started_at=2018-03-01T00:00:00Z&ended_at=2018-05-01T00:00:00Z'

Example Response #1

{
   "data": [
      {
         "extension_id": "abcdefg",
         "URL": "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/dynamic/WoW%20Armory_overview_v1_2018-04-30_2018-05-01_49e6bea0-fa6d-4f05-95c1-23cadbfe8e72.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAI7LAMHO6AIVYE6KQ%2F20180731%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180731T204129Z&X-Amz-Expires=60&X-Amz-Security-Token=FQoDYXdzEDMaDObdwyOVISdo6feHSSK3A9R9gMFeS5zuycuZaBk4tJemqCIazhsQJrpsehBoOufaQkCxrb8RD3oU0xC5pWrZe9kN%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-05-01.csv%22&X-Amz-Signature=652cde5a95ef86a46a558a1ccffed6f19b122a40125f17c160c8d2cddc81d975",
         "type": "overview_v1",
         "date_range": {
            "started_at": "2018-04-30T00:00:00Z",
            "ended_at": "2018-05-01T00:00:00Z"
         }
      }
   ]
}

Example Request #2

This gets the first 5 URLs (paginated) 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 -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/helix/analytics/extensions?first=5'

Example Response #2

{
   "data": [
      {
         "extension_id": "abcd",
         "URL": "https://twitch-piper-reports.s3-us-west-2.amazonaws.com/dynamic/WoW%20Armory_overview_v1_2018-04-30_2018-06-01_82a89379-e780-4c7a-b972-eaba280ec3b0.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAI7LAMHO6AIVYE6KQ%2F20180731%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180731T202847Z&X-Amz-Expires=60&X-Amz-Security-Token=FQoDYXdzEDMaDObdwyOVISdo6feHSSK3A9R9gMFeS5zuycuZaBk4tJemqCIazhsQJrpsehBoOufaQkCxrb8RD3oU0xC5pWrZe9kN%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_v1",
         "date_range": {
            "started_at": "2018-04-30T00:00:00Z",
            "ended_at": "2018-06-01T00:00:00Z"
         }
      },
      {
         "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. 

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

Required scope: analytics:read:games

URL

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

Required Query String Parameters

None

Optional Query String 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 (overview_v2) or 90 days (overview_v1) before the report was issued. The file contains one row of data per day.
type string Type of analytics report that is returned. If this is specified, the response includes one URL, for the specified report type. If this is not specified, the response includes multiple URLs (paginated), one for each report type available for the authenticated user’s games. Limit: 1. Valid values: "overview_v1", "overview_v2". Default: all report types for the authenticated user’s games.

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 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 of the overview_v2 report for game ID 493057, covering the period January 1, 2018 to March 1, 2018.

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

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. For the purpose of this example, assume the request is issued on June 14, 2018.

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

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_v1",
      "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

Required scope: bits:read

URL

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

Required Query String Parameters

None

Optional Query String 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 are given below. 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_name string Display name corresponding to user_id.

Example Request

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

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

Example Response

{
  "data": [
    {
      "user_id": "158010205",
      "user_name": "TundraCowboy",
      "rank": 1,
      "score": 12543
    },
    {
      "user_id": "7168163",
      "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 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.

Definition

Transaction: Record of a user exchanging Bits for an in-Extension digital good.

The API includes the following endpoint: GET helix/extensions/transactions

Description

Get the list of Extension Transactions for a given extension.

Authentication

App Access OAuth Token

Authorization

OAuth Token Client ID must match Extension Client ID.

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 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_name string Twitch Display Name of the broadcaster.
   user_id string Twitch User ID 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 -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'helix/extensions/transactions?extension_id=1234'

Example Response

{
     "data": [
          {
               "id": "74c52265-e214-48a6-91b9-23b6014e8041",
               "timestamp": "2019-01-28T04:15:53.325Z",
               "broadcaster_id": "439964613",
               "broadcaster_name": "chikuseuma",
               "user_id": "424596340",
               "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_name": "chikuseuma"
                "user_id": "439966926",
                "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"
     }
}

 

 

 

 

 

Create Clip

✎

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

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

Required scope: clips:edit

URL

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

Required Query String Parameter

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

Optional Query String 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 -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X POST 'https://api.twitch.tv/helix/clips?broadcaster_id=44322889'

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

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

None

URL

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

Required Query String 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 String 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. (Note that 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
broadcaster_id string User ID of the stream from which the clip was created.
broadcaster_name string Display name corresponding to broadcaster_id.
created_at string Date when the clip was created.
creator_id string ID of the user who created the clip.
creator_name string Display name corresponding to creator_id.
embed_url string URL to embed the clip.
game_id string ID of the game assigned to the stream when the clip was created.
id string ID of the clip being queried.
language string Language of the stream from which the clip was created.
pagination string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.
thumbnail_url string URL of the clip thumbnail.
title string Title of the clip.
url string URL where the clip can be viewed.
video_id string ID of the video from which the clip was created.
view_count int Number of times the clip has been viewed.

Example Request #1

This gets information for clip AwkwardHelplessSalamanderSwiftRage.

curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/helix/clips?id=AwkwardHelplessSalamanderSwiftRage'

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

Example Request #2

This gets the top 5 clips from broadcaster 1234.

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

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

Create Entitlement Grants Upload URL

✎

Creates a URL where you can upload a manifest file and notify users that they have an entitlement. Entitlements are digital items that users are entitled to use. Twitch entitlements are granted to users gratis or as part of a purchase on Twitch.

See the Drops Guide for details about using this endpoint to notify users about Drops.

Authentication

App access token

URL

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

Required Query String Parameters

Name Type Description
manifest_id string Unique identifier of the manifest file to be uploaded. Must be 1-64 characters.
type string Type of entitlement being granted. Only bulk_drops_grant is supported.

Optional Query String Parameters

None

Response Field

Field Type Description
url string The URL where you will upload the manifest file. This is the URL of a pre-signed S3 bucket. Lease time: 15 minutes.

Note: You must replace all occurrences of \u0026 with an ampersand (&) character. See the Drops Guide.

Example Request

This creates an award URL for manifest ID 123456789.

curl -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X POST 'https://api.twitch.tv/helix/entitlements/upload?manifest_id=123456789&type=bulk_drops_grant'

Example Response

{
  "data":[
    {
      "url": "https://twitch-ds-vhs-drops-granted-uploads-us-west-2-prod.s3-us-west-2.amazonaws.com/<clientID>/<time>-123456789.json?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=<credential>%2Fus-west-2%2Fs3%2Faws4_request\u0026X-Amz-Date=<date>\u0026X-Amz-Expires=900\u0026X-Amz-Security-Token=<token>\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=<signature>"
    }
  ]
}

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.

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 -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/helix/entitlements/codes?code=KUHXV-4GXYP-AKAKK&code=XZDDZ-5SIQR-RT5M3&user_id=156900877'

Example Response

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

 

Redeem Code

✎

Redeems one or more provided codes to the 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. This API requires that the caller is an authenticated Twitch user. The API is throttled to one request per second per authenticated user.

URL

https://api.twitch.tv/helix/entitlements/code

Authentication

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

Authorization

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

Query Params

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 -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X POST 'https://api.twitch.tv/helix/entitlements/codes?code=8CD5P-V3J92-2S6JY&code=PUN4G-HYFVP-MMFET'

Example Response

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

 

 

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

None

URL

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

Required Query String Parameters

None

Optional Query String 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 the game’s box art.
id string Game ID.
name string Game name.
pagination 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 -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/helix/games/top'

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

None

URL

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

Required Query String 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 instance, “Pokemon” will not return a list of Pokemon games; instead, query the specific Pokemon game(s) 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 String 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 -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/helix/games?id=493057'

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

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: https://help.twitch.tv/s/article/how-to-use-automod?language=en_US

Authorization

Requires OAuth 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 integer 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 ### integer 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.

​​​​​​POST helix/moderation/enforcements/status with body:
{
  "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
    }
  ]
}

 

Get Banned Events

✎

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

Authorization

Requires OAuth 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 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
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 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_name, user_id, user_name, and expires_at.

Example Request

Returns all bans and un-bans for Broadcaster 198704263.

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

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_name": "aan22209",
        "user_id": "424596340",
        "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_name": "aan22209",
        "user_id": "424596340",
        "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_name": "aan22209",
        "user_id": "424596340",
        "user_name": "quotrok",
        "expires_at": ""
      }
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjE5OTYwNDI2MzoyMDIxMjA1MzE6MUlQRnFtbHU5VzJxNG1YWGpVTHlNOHpYMHJiIn19"
  }
}

Get Banned Users

✎

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

Authentication

The following OAuth scope is required: 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
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

ParameterTypeDescription
user_idstringUser ID of a user who has been banned.
user_namestringDisplay name of a user who has been banned.
expires_atstringRFC3339 formatted timestamp for timeouts; empty string for bans.
paginationstringA cursor value, to be used in subsequent requests to specify the starting point of the next set of results.

 

Example Request

Gets the users who have been banned by Broadcaster 198704263.

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

Example Response

Shows that users glowillig and quotrok have been banned.

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

Get Moderators

✎

Returns all moderators in a channel.

Authorization

Requires OAuth Scope: moderation:read

URL

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

Pagination Support

Forward pagination only. 

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

Return Values

ParameterTypeDescription
user_idstringUser ID of a user who has been banned.
user_namestringDisplay name of a user who has been banned.
paginationstringA 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 -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/helix/moderation/moderators?broadcaster_id=198704263'

Example Response

{
  "data": [
    {
      "user_id": "424596340",
      "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

Requires OAuth Scope: moderation:read

URL

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

Pagination Support

Forward pagination only.

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 Parameter

Parameter Required Type Description
user_id no string Filters the results and only returns a status object for users who are banned in this channel and have a matching user_id.

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

Maximum: 100

Return Values

Parameter Type Description
id string User ID of the moderator.
event_type string Displays moderation.user.ban or moderation.user.unban
event_timestamp string RFC3339 formatted timestamp for events.
pagination 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.

Example Request

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

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

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_name": "aan22209",
        "user_id": "423374343",
        "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_name": "aan22209",
        "user_id": "423374343",
        "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_name": "aan22209",
        "user_id": "424596340",
        "user_name": "quotrok"
      }
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEwMDQ3MzA2NDo4NjQwNjU3MToxSVZCVDFKMnY5M1BTOXh3d1E0dUdXMkJOMFcifX0"
  }
}

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

None

URL

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

Required Query String Parameters

None

Optional Query String 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.
community_id string Returns streams in a specified community ID. You can specify up to 100 IDs.
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.
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
community_ids string[] Array of community IDs.
game_id string ID of the game being played on the stream.
id string Stream ID.
language string Stream language.
pagination 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_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 #1

This gets information about the 20 most active streams.

curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/helix/streams?first=20'

Example Response #1

{
  "data": [
    {
      "id": "26007494656",
      "user_id": "23161357",
      "user_name": "LIRIK",
      "game_id": "417752",
      "community_ids": [
        "5181e78f-2280-42a6-873d-758e25a7c313",
        "848d95be-90b3-44a5-b143-6e373754c382",
        "fd0eab99-832a-4d7e-8cc0-04d73deb2e54"
      ],
      "type": "live",
      "title": "Hey Guys, It's Monday - Twitter: @Lirik",
      "viewer_count": 32575,
      "started_at": "2017-08-14T16:08:32Z",
      "language": "en",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_lirik-{width}x{height}.jpg"
    },
       "tag_ids":  [
          "6ea6bca4-4712-4ab9-a906-e3336a9d8039"
        ]
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6MjB9fQ=="
  }
}

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 -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/helix/streams?first=20&after=eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6MjB9fQ=='

Example Response 2

{
  "data": [
    {
      "id": "26007351216",
      "user_id": "7236692",
      "user_name": "BillyBob",
      "game_id": "29307",
      "community_ids": [
        "848d95be-90b3-44a5-b143-6e373754c382",
        "fd0eab99-832a-4d7e-8cc0-04d73deb2e54",
        "ff1e77af-551d-4993-945c-f8ceaa2a2829"
      ],
      "type": "live",
      "title": "[Punday Monday] Necromancer - Dan's First Character - Maps - !build",
      "viewer_count": 5723,
      "started_at": "2017-08-14T15:45:17Z",
      "language": "en",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_dansgaming-{width}x{height}.jpg"
    },
    ...
   ],
   "pagination": {
     "cursor": "eyJiIjp7Ik9mZnNldCI6MH0sImEiOnsiT2Zmc2V0Ijo0MH19"
   }
}

Get Streams Metadata

✎

Gets metadata information about active streams playing Overwatch or Hearthstone. Streams are 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.

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

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

Authentication

None

URL

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

Required Query String Parameters

None

Optional Query String 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.
community_id string Returns streams in a specified community ID. You can specify up to 100 IDs.
first integer Maximum number of objects to return. Maximum: 100. Default: 20.
game_id string Returns streams broadcasting the specified game ID. You can specify up to 100 IDs.
language string Stream language. You can specify up to 100 languages.
user_id string Returns streams broadcast by one or more of the specified user IDs. You can specify up to 100 IDs.
user_login string Returns streams broadcast by one or more of the specified user login names. You can specify up to 100 names.

Response Fields

FieldTypeDescription

game_id

stringID of the game being played on the stream: 488552 (Overwatch), 138585 (Hearthstone), or null (neither Overwatch nor Hearthstone metadata is available).
hearthstoneobjectObject containing the Hearthstone metadata, if available; otherwise, null.
 broadcaster
opponent		objectHearthstone metadata about the broadcaster and the broadcaster’s opponent.
  heroobjectMetadata about the Hearthstone hero selected by the broadcaster/opponent. null if empty.
   classstringClass of the Hearthstone hero.
   namestringName of the Hearthstone hero.
   typestringType of Hearthstone hero.
overwatchobjectObject containing the Overwatch metadata, if available; otherwise, null.
 broadcasterobjectOverwatch metadata about the broadcaster.
  heroobjectMetadata about the Overwatch hero selected by the broadcaster. null if empty.
   abilitystringAbility being used by the broadcaster.
   namestringName of the Overwatch hero.
   rolestringRole of the Overwatch hero.
paginationstringA cursor value, to be used in a subsequent request to specify the starting point of the next set of results.
user_idstringUser ID of the streamer (broadcaster).
user_namestringLogin name corresponding to user_id.

Example Request

This gets metadata information about the 20 most active streams.

curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/helix/streams/metadata'

Example Response

{
  "data": [
    {
      "user_id": "23161357",
      "user_name": "LIRIK",
      "game_id": "488552",
      "overwatch": {
        "broadcaster": {
          "hero": {
            "role": "Offense",
            "name": "Soldier 76",
            "ability": "Heavy Pulse Rifle"
          }
        }
      },
      "hearthstone": null
    },
    {
      "user_id": "1564968",
      "user_name": "OnlyATest",
      "game_id": "138585",
      "overwatch": null,
      "hearthstone": {
        "broadcaster": {
          "hero": {
            "type": "Classic hero",
            "class": "Shaman",
            "name": "Thrall"
          }
        },
        "opponent": {
          "hero": {
            "type": "Classic hero",
            "class": "Warrior",
            "name": "Garrosh Hellscream"
          }
        }
      }
    },
    {
      "user_id": "5848726",
      "user_name": "FooBar",
      "game_id": null,
      "overwatch": null,
      "hearthstone": null
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6MjB9fQ=="
  }
}

Create Stream Marker

✎

Creates a marker in the stream of a user specified by a 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

Required scope: user:edit:broadcast

URL

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

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.

Required Query String Parameters

None

Optional Query String Parameters

None

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 -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X POST 'https://api.twitch.tv/helix/streams/markers' \
-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

Required scope: user:read:broadcast

URL

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

Required Query String 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 String 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.
paginationstringA 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.
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 -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/helix/streams/markers?user_id=123&first=5'

Example Response

{
  "data": [
    {
      "user_id": "123",
      "user_name": "Display Name",
      "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 a broadcaster’s subscriptions.

Authentication

The current user is determined by the OAuth token provided in the Authorization header.

Authorization

Required OAuth Scope: channel:read:subscriptions

Broadcasters can only request their own subscriptions.

URL

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

Query Parameters

All parameters are required.

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

Return Values

Parameter Type Description
broadcaster_id string User ID of the broadcaster. 
broadcaster_name string Display name of the broadcaster.
is_gift Boolean Determines if the subscription is a gift subscription.
tier string Type of subscription (Tier 1, Tier 2, Tier 3).
1000 = Tier 1, 2000 = Tier 2, 3000 = Tier 3 subscriptions.
plan_name string Name of the subscription.
user_id string ID of the subscribed user.
user_name string Display name of the subscribed user. 

Example Request

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

Example Response


{
  "data": [
    {
      "broadcaster_id": "123"
      "broadcaster_name": "test_user"
      "is_gift" true,
      "tier": "1000",
      "plan_name": "The Ninjas",
      "user_id": "123",
      "user_name": "snoirf",
    },
    …
  ],
  "pagination": {
    "cursor": "xxxx"
  }
}

Get Broadcaster's Subscribers

✎

Gets broadcaster’s subscriptions by user ID (one or more).

Authentication

OAuth Token (e.g. User Access Token)

The current user is determined by the OAuth token provided in the Authorization header.

Authorization

Required OAuth Scope: channel:read:subscriptions

Users can only request their own subscriptions.

URL

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

Query Parameters

All parameters are required.

Parameter Type Description
broadcaster_id string ID of the broadcaster. Must match the User ID in the Bearer token.
user_id string Unique identifier of account to get subscription status of. Accepts up to 100 values.

Return Values

Parameter Type Description
broadcaster_id string User ID of the broadcaster. 
broadcaster_name string Display name of the broadcaster.
is_gift Boolean Determines if the subscription is a gift subscription.
tier string Type of subscription (Tier 1, Tier 2, Tier 3).
1000 = Tier 1, 2000 = Tier 2, 3000 = Tier 3 subscriptions.
plan_name string Name of the subscription.
user_id string Unique identifier of account to get subscription status of. 
user_name string Display name of the subscribed user.

Example Request

curl -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \  -X GET 'https://api.twitch.tv/helix/subscriptions?broadcaster_id=id1&user_id=id2&user_id=id3'

Example Response

{
  "data":[
   {
      "broadcaster_id":"123",
      "broadcaster_name":"test_user",
      "is_gift":true,
      "tier":"1000",
      "plan_name":"The Ninjas",
      "user_id":"123",
      "user_name":"lyrrad"
    }
  ],
  "pagination":{
    "cursor":"xxxx"
  }
}

Get Subscription Events

✎

Returns all subscription events for the past five days.

Authorization

Requires OAuth scope: channel:read:subscriptions

Pagination Support

Forward pagination.

Required Query Parameter

You must provide either the broadcaster_id or id parameter.

Parameter Type Description
broadcaster_id string User ID of the broadcaster. Must match the User ID in the Bearer token.
id string Retrieve a single event by the event ID. 
Maximum: 1

Optional Query Parameters

Parameter Type Description
user_id string ID of the subscribed user. Currently only one user_id at a time can be queried.

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

Maximum: 100

Return Values

Parameter Type Description
id string ID of the event.
event_type string The type of event in the event_data payload. See possible values:

subscriptions.subscribe: When the subscription payment is processed and the user has officially started their subscription.

subscriptions.unsubscribe: When a user’s subscription ends.

subscriptions.notification: Returns when a user who is subscribed to a broadcaster notifies the broadcaster of their subscription in the chat.
event_timestamp string RFC3339 formatted timestamp for when the event occurred.
version string Event version.
event_data object Event payload.
   broadcaster_id string ID of the broadcaster.
   broadcaster_name string Display name of the broadcaster.
   is_gift Boolean Determines if the subscription is a gift.
   plan_name string Broadcaster’s name for the subscription tier.
   tier string Subscription tier. 
Note: Tier 1 and Prime subscriptions are returned as “1000”.
   user_id string ID of the subscriber.
   user_name string Display name of the subscriber.
   message string The chat message. It can be whatever message appears in the chat. 
It is an optional field, depending on the event type.
pagination string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.

Example Request

GET helix/subscriptions/events?broadcaster_id=113627897

Example Response

These example responses are filtered by broadcaster. You can also filter by type.

At 2019-02-03T08:14:19 dallas subscribed to the broadcaster Birdman616:

​​​​​​{
  "data": [

      "id": "1Gf161qjQtk0mOMD4VeIMjTGPUk",
      "event_type": "subscriptions.subscribe",
      "event_timestamp": "2019-02-03T08:14:19Z",
      "version": "1.0",
      "event_data": {
        "broadcaster_id": "113627897",
        "broadcaster_name": "Birdman616",
        "is_gift": false,
        "plan_name": "Channel Subscription (Birdman616)",
        "tier": "1000",
        "user_id": "44322889",
        "user_name": "dallas"

],
"pagination": {
  "cursor":
"eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEzODU0MjYwMDoxNTU1MDg4NDU4OjFKbTdYV1RvZVFaWWZPV0p1clAzUEdPRVc4VSJ9fQ"

}

At 2019-02-03T08:14:19Z dallas unsubscribed from the broadcaster Birdman616: 

​​​​​​{
  "data": [

      "id": "1Gf15xHu9Kqq8G43Hox2skNSWTA",
      "event_type": "subscriptions.unsubscribe",
      "event_timestamp": "2019-02-03T08:14:19Z",
      "version": "1.0",
      "event_data": {
        "broadcaster_id": "113627897",
        "broadcaster_name": "Birdman616",
        "is_gift": true,
        "plan_name": "",
        "tier": "",
        "user_id": "44322889",
        "user_name": "dallas"

],
"pagination": {
  "cursor":
"eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjEzODU0MjYwMDoxNTU1MDg4NDU4OjFKbTdYV1RvZVFaWWZPV0p1clAzUEdPRVc4VSJ9fQ"

}

Note:plan_name and tier are empty fields. This will always be the case for unsubscribe.

At 2019-04-14T05:24:46Z The_LucifersDog notified Chibirobol of their subscription in chat, sending a message to Chibirobol that said, “You are the best”.

{
    "id": "1JqP7PvuK7Q9Cc0ZUpdwV9MfnBz",
    "event_type": "subscriptions.notification",
    "event_timestamp": "2019-04-14T05:24:46Z",
    "version": "1.0",
    "event_data": {
        "broadcaster_id": "39592219",
        "broadcaster_name": "Chibirobo1",
        "is_gift": false,
        "plan_name": "",
        "tier": "",
        "user_id": "183401728",
        "user_name": "The_LucifersDog",
        "message": "You are the best" }

],
"pagination": {
        "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IjM5NTkyMjE5OjE1NTUyMDMwMzA6MUpwcmxRbndLT0xnemVEN3pPaWFaRWNab3JuIn19"

}
​​​

 

 

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 String Parameters

None

Optional Query String 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
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 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 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 three stream tags defined by Twitch.

curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \ -X GET 'https://api.twitch.tv/helix/tags/streams?first=3'

Example Response

{
  "data": [
    {
      "tag_id": "621fb5bf-5498-4d8f-b4ac-db4d40d401bf",
      "is_auto": false,
      "localization_names": {
        "bg-bg": "Завършване без продължаване",
        "cs-cz": "Na jeden z&aacute;tah", "da-dk": "1 Continue klaret",
        "de-de": "Mit nur 1 Leben",
        "el-gr": "1 χωρίς συνέχεια",
        "en-us": "1 Credit Clear",
        ...
      },
      "localization_descriptions": {
        "bg-bg": "За потоци с акцент върху завършване на аркадна игра с монети, в която не се използва продължаване",
        "cs-cz": "Pro vys&iacute;l&aacute;n&iacute; s důrazem na plněn&iacute; mincov&yacute;ch ark&aacute;dov&yacute;ch her bez použit&iacute; pokračov&aacute;n&iacute;.",
        "da-dk": "Til streams med v&aelig;gt p&aring; at gennemf&oslash;re et arkadespil uden at bruge continues",
        "de-de": "F&uuml;r Streams mit dem Ziel, ein Coin-op-Arcade-Game mit nur einem Leben abzuschlie&szlig;en.",
        "el-gr": "Για μεταδόσεις με έμφαση στην ολοκλήρωση παλαιού τύπου ηλεκτρονικών παιχνιδιών που λειτουργούν με κέρμα, χωρίς να χρησιμοποιούν συνέχειες",
        "en-us": "For streams with an emphasis on completing a coin-op arcade game without using any continues",
        ...
      }
    },
    {
      "tag_id": "7b49f69a-5d95-4c94-b7e3-66e2c0c6f6c6",
      "is_auto": false,
      "localization_names": {
        "bg-bg": "Дизайн",
        "cs-cz": "Design",
        "da-dk": "Design",
        "de-de": "Design",
        "el-gr": "Σχέδιο",
        "en-us": "Design",
        ...
      },
      "localization_descriptions": {
        "en-us": "For streams with an emphasis on the creative process of designing an object or system"
      }
    },
    {
      "tag_id": "1c628b75-b1c3-4a2f-9d1d-056c1f555f0e",
      "is_auto": true,
      "localization_names": {
        "bg-bg": "Шампион: Lux",
        "cs-cz": "Šampion: Lux",
        "da-dk": "Champion: Lux",
        ...
      },
      "localization_descriptions": {
      "en-us": "For streams featuring the champion Lux in League of Legends"
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6ImV5SnBaQ0k2ZXlKQ0lqcHVkV3hzTENKQ1QwOU1JanB1ZFd4c0xDS kNVeUk2Ym5Wc2JDd2lUQ0k2Ym5Wc2JDd2lUU0k2Ym5Wc2JDd2lUaUk2Ym5Wc2JDd2lUbE1pT201MWJHd3NJazV WVEV3aU9tNTFiR3dzSWxNaU9pSXhZell5T0dJM05TMWlNV016TFRSaE1tWXRPV1F4WkMwd05UWmpNV1kxTlRWb U1HVWlMQ0pUVXlJNmJuVnNiSDE5In19"
  }
}

Get Stream Tags

✎

Gets the list of tags for a specified stream (channel).
The response has a JSON payload with a data field containing an array of tag elements.

Authentication

App access token

URL

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

Required Query String Parameter

Name Type Description
broadcaster_id string ID of the stream thats tags are going to be fetched

Optional Query String Parameters

None

Response Fields

Field Type Description
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 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.
tag_id string ID of the tag. 

Example Request

This gets the tags for broadcaster 257788195’s stream.

curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/helix/streams/tags?broadcaster_id=257788195'

Example Response

{
     "data":
     [
          {
               "tag_id": "621fb5bf-5498-4d8f-b4ac-db4d40d401bf",
               "is_auto": false, "localization_names": {
               "bg-bg": "Завършване без продължаване",
               "cs-cz": "Na jeden z&aacute;tah", "da-dk": "1
               Continue klaret", ... },

               "localization_descriptions": {
                      "bg-bg": "За потоци с акцент върху завършване на аркадна игра с монети, в която не се използва продължаване",
                      "cs-cz": "Pro vys&iacute;l&aacute;n&iacute; s důrazem na plněn&iacute; mincov&yacute;ch ark&aacute;dov&yacute;ch her bez použit&iacute; pokračov&aacute;n&iacute;.",
                      "da-dk": "Til streams med v&aelig;gt p&aring; at gennemf&oslash;re et arkadespil uden at bruge continues", ...
          } },
           {
                "tag_id": "79977fb9-f106-4a87-a386-f1b0f99783dd",
                "is_auto": false, "localization_names": {
                "bg-bg": "PvE", "cs-cz": "PvE", ... },

                "localization_descriptions": {
             "bg-bg": "За потоци с акцент върху PVE геймплей",
             "cs-cz": "Pro vys&iacute;l&aacute;n&iacute; s důrazem na hratelnost \"hr&aacute;č vs. prostřed&iacute;\".",
             "da-dk": "Til streams med v&aelig;gt p&aring; spil, hvor det er spilleren mod omgivelserne.",
             ... } } ] }

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

Required scope: user:edit:broadcast

URL

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

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.

Maximum of 100 supported.

Required Query String Parameter

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

Optional Query String Parameters

None

Example Request

This adds tags to broadcaster 257788195’s stream.

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

Example Response

204: No Content

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

Optional scope: user:read:email

If this is provided, the response includes the user’s email address.

URL

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

Required Query String Parameters

None

Optional Query String 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.
email string User’s email address. Returned if the request includes the user:read:email scope.
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 int Total number of views of the user’s channel.

Example Request

This gets information about user 44322889.

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

Example Response

{
  "data": [{
    "id": "44322889",
    "login": "dallas",
    "display_name": "dallas",
    "type": "staff",
    "broadcaster_type": "",
    "description": "Just a gamer playing games and chatting. :)",
    "profile_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-profile_image-1a2c906ee2c35f12-300x300.png",
    "offline_image_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/dallas-channel_offline_image-1a2c906ee2c35f12-1920x1080.png",
    "view_count": 191836881,
    "email": "login@provider.com"
  }]
}

Get Users Follows

✎

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

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

None

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 String Parameters

None

Optional Query String 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_namestringDisplay name corresponding to from_id.
paginationstringA 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_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 -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/helix/users/follows?to_id=23161357'

Example Response

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

Update User

✎

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

Authentication

Required scope: user:edit

URL

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

Required Query String Parameters

None

Optional Query String Parameters

None

Response Fields

Response fields are the same as for Get Users.

Example Request

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

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

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

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

Required scope: user:read:broadcast

URL

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

Required Query String Parameters

None

Optional Query String 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 -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/helix/users/extensions/list'

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

Optional scope: user:read:broadcast or user:edit:broadcast

URL

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

Required Query String Parameters

None

Optional Query String 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 -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/helix/users/extensions'

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

Required scope: user:edit:broadcast

URL

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

Required Query String Parameters

None

Optional Query String 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 -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X PUT 'https://api.twitch.tv/helix/users/extensions'
-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 string parameters.

Authentication

None

URL

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

Required Query String 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 string 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 String 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.
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
created_at string Date when the video was created.
description string Description of the video.
duration string Length of the video.
id string ID of the video.
language string Language of the video.
pagination string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.
published_at string Date when the video was published.
thumbnail_url object Template URL for the thumbnail of the video.
title string Title of the video.
type string Type of video. Valid values: "upload", "archive", "highlight".
url object URL of the video.
user_id string ID of the user who owns the video.
user_name string Display name corresponding to user_id.
view_count int Number of times the video has been viewed.
viewable string Indicates whether the video is publicly viewable. Valid values: "public", "private".

Example Request

This gets information about the video with ID 234482848.

curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/helix/videos?id=234482848'

Example Response

{
  "data": [{
    "id": "234482848",
    "user_id": "67955580",
    "user_name": "ChewieMelodies",
    "title": "-",
    "description": "",
    "created_at": "2018-03-02T20:53:41Z",
    "published_at": "2018-03-02T20:53:41Z",
    "url": "https://www.twitch.tv/videos/234482848",
    "thumbnail_url": "https://static-cdn.jtvnw.net/s3_vods/bebc8cba2926d1967418_chewiemelodies_27786761696_805342775/thumb/thumb0-%{width}x%{height}.jpg",
    "viewable": "public",
    "view_count": 142,
    "language": "en",
    "type": "archive",
    "duration": "3h8m33s"
  }],
  "pagination":{"cursor":"eyJiIjpudWxsLCJhIjoiMTUwMzQ0MTc3NjQyNDQyMjAwMCJ9"}
}

Get Webhook Subscriptions

✎

Gets the Webhook subscriptions of a user 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 String Parameters

None

Optional Query String 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”).
paginationstringA 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. Note 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 -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/helix/webhooks/subscriptions?first=10&after=eyJiIjpudWxsLCJhIjp7IkN1cnNvciI6IiJ9fQ'

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"
   }
}
+
Docs Status Support Showcase Blog