New 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 1 minute. 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 1 minute. 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.
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.
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.
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.
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.
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 Webhook subscriptions, 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 1 minute. For detail about analytics and the fields returned, see the Insights & Analytics guide.

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

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

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

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.

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",
            "rank": 1,
            "score": 12543
        },
        {
            "user_id": "7168163",
            "rank": 2,
            "score": 6900
        },
    ],
    "date_range": {
        "started_at": "2018-02-05T08:00:00Z",
        "ended_at": "2018-02-12T08:00:00Z"
    },
    "total": 2
}

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.
`first`	integer	Maximum number of objects to return. Maximum: 100. Default: 20.

Response Fields

Field	Type	Description
`broadcaster_id`	string	User ID of the stream from which the clip was created.
`created_at`	string	Date when the clip was created.
`creator_id`	string	ID of the user who created the clip.
`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",
    "creator_id": "53834192",
    "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",
    "creator_id":"123456",
    "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 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"
  }]
}

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 Streams

✎

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

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

Authentication

None

URL

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

Required Query String Parameters

None

Optional Query String Parameters

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

Response Fields

Field	Type	Description
`community_ids`	string[]	Array of community IDs.
`game_id`	string	ID of the game being played on the stream.
`id`	string	Stream ID.
`language`	string	Stream language.
`pagination`	string	A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.
`started_at`	string	UTC timestamp.
`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.
`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",
      "game_id": "417752",
      "community_ids": [
        "5181e78f-2280-42a6-873d-758e25a7c313",
        "848d95be-90b3-44a5-b143-6e373754c382",
        "fd0eab99-832a-4d7e-8cc0-04d73deb2e54"
      ],
      "type": "live",
      "title": "Hey Guys, It's Monday - Twitter: @Lirik",
      "viewer_count": 32575,
      "started_at": "2017-08-14T16:08:32Z",
      "language": "en",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_lirik-{width}x{height}.jpg"
    },
    ...
  ],
  "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",
      "game_id": "29307",
      "community_ids": [
        "848d95be-90b3-44a5-b143-6e373754c382",
        "fd0eab99-832a-4d7e-8cc0-04d73deb2e54",
        "ff1e77af-551d-4993-945c-f8ceaa2a2829"
      ],
      "type": "live",
      "title": "[Punday Monday] Necromancer - Dan's First Character - Maps - !build",
      "viewer_count": 5723,
      "started_at": "2017-08-14T15:45:17Z",
      "language": "en",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_dansgaming-{width}x{height}.jpg"
    },
    ...
   ],
   "pagination": {
     "cursor": "eyJiIjp7Ik9mZnNldCI6MH0sImEiOnsiT2Zmc2V0Ijo0MH19"
   }
}

Get Streams Metadata

✎

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

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

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

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

Authentication

None

URL

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

Required Query String Parameters

None

Optional Query String Parameters

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

Response Fields

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

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",
      "game_id": "488552",
      "overwatch": {
        "broadcaster": {
          "hero": {
            "role": "Offense",
            "name": "Soldier 76",
            "ability": "Heavy Pulse Rifle"
          }
        }
      },
      "hearthstone": null
    },
    {
      "user_id": "1564968",
      "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",
      "game_id": null,
      "overwatch": null,
      "hearthstone": null
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjp7Ik9mZnNldCI6MjB9fQ=="
  }
}

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.

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.
`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`	object	ID of the user being followed by the `from_id` user.
`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",
         "to_id": "23161357",
         "followed_at": "2017-08-22T22:55:24Z"
      },
      {
         "from_id": "113627897",
         "to_id": "23161357",
         "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.
`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",
    "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 Webhook subscriptions, 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 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-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"
   }
}