Contents

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.

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 Parameter

Name Type Description
extension_id string Extension ID. 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, pointing to separate analytics reports for each of the authenticated user’s extensions.

Response Fields

FieldTypeDescription
extension_idstringID of the extension whose analytics data is being provided.
URLstringURL 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 extension ID abcdefgh.

curl -H 'Authorization: Bearer cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/helix/analytics/extensions?extension_id=abcdefgh'

Example Response

{"data":
   [
      {
         "extension_id":"abcdefgh", "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%3Dextabcd-overview-2018-03-12.csv&X-Amz-Signature=49cc07cbd9d753b00315b66f49b9e4788570062ff3bd956288ab4f164cf96708",
      }
   ]
}

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.
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. 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.
ended_at string Ending date/time for returned reports, in RFC3339 format. 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).

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

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

Any + operator should be URL encoded.

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

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

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

Response Fields

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

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

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.

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

FieldTypeDescription

game_id

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

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

Required Query String Parameters

None

Optional Query String Paramaters

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

Response Fields

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

Example Request

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

curl -H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/helix/users/follows?to_id=23161357

Example Response

{
   "total": 12345,
   "data":
   [
      {
         "from_id": "171003792",
         "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

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

Example Request

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

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

Example Response

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

Get User Active Extensions

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

Authentication

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

URL

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

Required Query String Parameters

None

Optional Query String Parameter

NameTypeDescription
user_idstring

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

Response Fields

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

Example Request

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

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

Example Response

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

Update User Extensions

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

Authentication

Required scope: user:edit:broadcast

URL

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

Required Query String Parameters

None

Optional Query String Parameters

None

Response Fields

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

Example Request

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

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

Example Response

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

Get Videos

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

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

Authentication

None

URL

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

Required Query String Parameters

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

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

Optional Query String Parameters

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

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

Response Fields

Fields Type Description
created_at string Date when the video was created.
description string Description of the video.
duration string Length of the video.
id string ID of the video.
language string Language of the video.
pagination string A cursor value, to be used in a subsequent request to specify the starting point of the next set of results.
published_at string Date when the video was published.
thumbnail_url object Template URL for the thumbnail of the video.
title string Title of the video.
type string Type of video. Valid values: "upload", "archive", "highlight".
url object URL of the video.
user_id string ID of the user who owns the video.
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"}
}
+