New Twitch API Reference

Resource	Endpoint	Description
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 Clip	Gets information about a specified clip or gets the top clips for a specified broadcaster or game. 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 Game Analytics	Get a URL that game developers can use to download analytics for their games in a CSV format. The URL is valid for 1 minute. For detail about game analytics and the fields returned, see the Game Developer Analytics guide.
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.
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.

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 Clip, with the clip ID that is returned here. If Get Clip returns a valid clip, your clip creation was successful. If, after 15 seconds, you still have not gotten back a valid clip from Get Clip, 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.

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 Clip

Gets information about a specified clip or gets the top clips for a specified broadcaster or game.

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 top clips are returned. The number of clips returned is determined by the `first` query-string parameter (default: 20).
`game_id`	string	ID of the game for which top clips are returned. The number of clips returned is determined by the `first` query-string parameter (default: 20).
`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

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

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.

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 Game Analytics

Get 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 game analytics and the fields returned, see the Game Developer Analytics guide.

Authentication

Required scope: analytics:read:games

URL

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

Required Query String Parameters

None

Optional Query String Parameter

Name	Type	Description
`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, pointing to separate analytics reports for each of the authenticated user’s games.

Response Fields

Field	Type	Description
`game_id`	string	ID of the game whose analytics data is being provided.
`URL`	string	URL to the downloadable CSV file containing analytics data. Valid for 1 minute.

Example Request

This gets the URL for a downloadable CSV of analytics data for game ID 493057.

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

Example Response

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

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

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

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"`, `"vodcast"`, or `""`.
`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

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.
`type`	string	Stream type: `"all"`, `"live"`, `"vodcast"`. Default: `"all"`.
`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

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 both login names and user IDs; e.g.,
GET https://api.twitch.tv/helix/users?login=<login name>&id=<user ID>...

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.

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>

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 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"`, `"month"`, and `"week"`. Default: `"all"`.
`sort`	string	Sort order of the videos. Valid values: `"time"`, `"trending"`, and `"views"`. Default: `"time"`.
`type`	string	Type of video. Valid values: `"all"`, `"upload"`, `"archive"`, and `"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"}
}