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

Field	Type	Description
`ended_at`	string	Report end date/time.
`extension_id`	string	ID of the extension 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 `extension_id` is not specified in the request.
`started_at`	string	Report start date/time. Note this may differ from (be later than) the `started_at` value in the request; the response value is the date when data for the extension is available.
`type`	string	Type of report.
`URL`	string	URL to the downloadable CSV file containing analytics data. Valid for 5 minutes.

Example Request #1

This gets the 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

Name	Type	Description
`count`	integer	Number of results to be returned. Maximum: 100. Default: 10.
`period`	string	Time period over which data is aggregated (PST time zone). This parameter interacts with `started_at`. Valid values 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_at`	string	Timestamp for the period over which the returned data is aggregated. Must be in RFC 3339 format. If this is not provided, data is aggregated over the current period; e.g., the current day/week/month/year. This value is ignored if `period` is `"all"`. Any `+` operator should be URL encoded. Currently, the HH:MM:SS part of this value is used only to identify a given day in PST and otherwise ignored. For example, if the `started_at` value resolves to 5PM PST yesterday and `period` is `"day"`, data is returned for all of yesterday.
`user_id`	string	ID of the user whose results are returned; i.e., the person who paid for the Bits. As long as `count` is greater than 1, the returned data includes additional users, with Bits amounts above and below the user specified by `user_id`. If `user_id` is not provided, the endpoint returns the Bits leaderboard data across top users (subject to the value of `count`).

Response Fields

Field	Type	Description
`ended_at`	string	End of the date range for the returned data.
`rank`	integer	Leaderboard rank of the user.
`score`	integer	Leaderboard score (number of Bits) of the user.
`started_at`	string	Start of the date range for the returned data.
`total`	integer	Total number of results (users) returned. This is `count` or the total number of entries in the leaderboard, whichever is less.
`user_id`	string	ID of the user (viewer) in the leaderboard entry.
`user_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	string	Developer-generated identifier for mapping messages to results.
`msg_text`	yes	string	Message text.
`user_id`	yes	string	User ID of the sender.

Return Values

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

Example Request

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

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

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.
`before`	no	string	Cursor for backward pagination: tells the server where to start fetching the next set of results in a multi-page response. This applies only to queries without `user_id`. If a `user_id` is specified, it supersedes any cursor/offset. combinations. The cursor value specified here is from the `pagination` response field of a prior query.

Return Values

Parameter	Type	Description
`user_id`	string	User ID of a user who has been banned.
`user_name`	string	Display name of a user who has been banned.
`expires_at`	string	RFC3339 formatted timestamp for timeouts; empty string for bans.
`pagination`	string	A 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

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.

Return Values

Parameter	Type	Description
`user_id`	string	User ID of a user who has been banned.
`user_name`	string	Display name of a user who has been banned.
`pagination`	string	A cursor value, to be used in subsequent requests to specify the starting point of the next set of results.

Example Request

This request returns any moderators for Broadcaster ID 198704263.

curl -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/helix/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.
`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
`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",
      "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",
      "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.
`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

Field	Type	Description
`game_id`	string	ID of the game being played on the stream: `488552` (Overwatch), `138585` (Hearthstone), or `null` (neither Overwatch nor Hearthstone metadata is available).
`hearthstone`	object	Object containing the Hearthstone metadata, if available; otherwise, `null`.
`broadcaster` `opponent`	object	Hearthstone metadata about the broadcaster and the broadcaster’s opponent.
`hero`	object	Metadata about the Hearthstone hero selected by the broadcaster/opponent. `null` if empty.
`class`	string	Class of the Hearthstone hero.
`name`	string	Name of the Hearthstone hero.
`type`	string	Type of Hearthstone hero.
`overwatch`	object	Object containing the Overwatch metadata, if available; otherwise, `null`.
`broadcaster`	object	Overwatch metadata about the broadcaster.
`hero`	object	Metadata about the Overwatch hero selected by the broadcaster. `null` if empty.
`ability`	string	Ability being used by the broadcaster.
`name`	string	Name of the Overwatch hero.
`role`	string	Role of the Overwatch hero.
`pagination`	string	A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.
`user_id`	string	User ID of the streamer (broadcaster).
`user_name`	string	Login 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

Name	Type	Parameter
`user_id`	string	ID of the broadcaster in whose live stream the marker is created.

Optional Body Parameter

Name	Type	Parameter
`description`	string	Description of or comments on the marker. Max length is 140 characters.

Required Query String Parameters

None

Optional Query String Parameters

None

Response Fields

Field	Type	Description
`created_at`	string	RFC3339 timestamp of the marker.
`description`	string	Description of the marker.
`id`	string	Unique ID of the marker.
`position_seconds`	integer	Relative offset (in seconds) of the marker, from the beginning of the stream.

Example Request

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

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

Name	Type	Description
`user_id`	string	ID of the broadcaster from whose stream markers are returned.
`video_id`	string	ID of the VOD/video whose stream markers are returned.

Optional Query 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`	string	Number of values to be returned when getting videos by user or game ID. Limit: 100. Default: 20.

Response Fields

Field	Type	Description
`id`	string	ID of the marker.
`created_at`	string	RFC3339 timestamp of the marker.
`description`	string	Description of the marker.
`pagination`	string	A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. If this is empty, you are at the last page.
`position_seconds`	integer	Relative offset (in seconds) of the marker, from the beginning of the stream.
`URL`	string	A link to the stream with a query parameter that is a timestamp of the marker’s location.
`user_id`	string	ID of the user whose markers are returned.
`user_name`	string	Display name corresponding to `user_id`.
`video_id`	string	ID of the stream (VOD/video) that was marked.

Example Request

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

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

Required Query Parameter

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

Optional Query Parameter

Parameter	Type	Description
`user_id`	string	Returns broadcaster’s subscribers. 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	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 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

Field	Type	Description
`followed_at`	string	Date and time when the `from_id` user followed the `to_id` user.
`from_id`	string	ID of the user following the `to_id` user.
`from_name`	string	Display name corresponding to `from_id`.
`pagination`	string	A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.
`to_id`	string	ID of the user being followed by the `from_id` user.
`to_name`	string	Display name corresponding to `to_id`.
`total`	int	Total number of items returned. If only `from_id` was in the request, this is the total number of followed users. If only `to_id` was in the request, this is the total number of followers. If both `from_id` and `to_id` were in the request, this is 1 (if the "from" user follows the "to" user) or 0.

Example Request

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

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

Field	Type	Description
`can_activate`	boolean	Indicates whether the extension is configured such that it can be activated.
`id`	string	ID of the extension.
`name`	string	Name of the extension.
`type`	string array	Types for which the extension can be activated. Valid values: `"component"`, `"mobile"`, `"panel"`, `"overlay"`.
`version`	string	Version of the extension.

Example Request

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

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

Name	Type	Description
`user_id`	string	ID of the user whose installed extensions will be returned. Limit: 1.

Response Fields

Field	Type	Description
`active`	boolean	Activation state of the extension, for each extension type (component, overlay, mobile, panel). If `false`, no other data is provided.
`component`	map	Contains data for video-component Extensions.
`id`	string	ID of the extension.
`name`	string	Name of the extension.
`overlay`	map	Contains data for video-overlay Extensions.
`panel`	map	Contains data for panel Extensions.
`version`	string	Version of the extension.
`x`	int	(Video-component Extensions only) X-coordinate of the placement of the extension.
`y`	int	(Video-component Extensions only) Y-coordinate of the placement of the extension.

Example Request

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

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

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`	string	Number of values to be returned per page. Limit: 100. Default: 20.

Response Fields

Field	Type	Description
`callback`	string	The callback provided for this subscription.
`expires_at`	string	Date and time when this subscription expires. Encoded as RFC3339. The timezone is always UTC (“Z”).
`pagination`	string	A cursor value, to be used in a subsequent request to specify the starting point of the next set of results. If this is empty, you are at the last page.
`topic`	string	The topic used in the initial subscription.
`total`	int	A 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"
   }
}