Twitch Helix

Helix is the latest version of Twitch API

class twitch.helix.TwitchHelix(client_id=None, oauth_token=None client_secret=None, scopes=None)

This class provides methods for easy access to Twitch Helix API.

Parameters:
  • client_id (string) – Client ID you get from your registered app on Twitch
  • oauth_token (string) – OAuth token, if you already have it, otherwise use client_secret and scopes then call get_oauth to generate it
  • client_secret (string) – Client secret. Only used by get_oauth and should only be present if oauth_token is not set
  • scopes (string) – Twitch scopes that we want the OAuth token to have. Only used by get_oauth and should only be present if oauth_token is not set

Basic usage with oauth_token set:

import twitch
client = twitch.TwitchHelix(client_id='<client_id>', oauth_token='<oauth_token>')
client.get_streams()

Basic usage with fetching the oauth token on initialization:

import twitch
client = twitch.TwitchHelix(client_id='<client_id>', client_secret='<client_secret>', scopes=[twitch.constants.OAUTH_SCOPE_ANALYTICS_READ_EXTENSIONS])
client.get_oauth()
client.get_streams()
classmethod get_oauth(clip_id)

Gets access token with access to the requested scopes and stores the token on the class for future usage

classmethod get_clips(broadcaster_id=None, game_id=None, clip_ids=None, after=None, before=None, started_at=None, ended_at=None, page_size=20)

Gets clip information by clip ID (one or more), broadcaster ID (one only), or game ID (one only).

Parameters:
  • broadcaster_id (string) – Broadcaster ID for whom clips are returned. The number of clips returned is determined by the page_size parameter (Default: 20 Max: 100). Results are ordered by view count.
  • game_id (string) – Game ID for which clips are returned. The number of clips returned is determined by the page_size parameter (Default: 20 Max: 100). Results are ordered by view count.
  • clip_ids (list) – List of clip IDS being queried. Limit: 100.
  • after (optional) (string) – Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response.
  • before (optional) (string) – Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response.
  • started_at (optional) (string) – Starting date/time for returned clips, in RFC3339 format. (The seconds value is ignored.) If this is specified, ended_at also should be specified; otherwise, the ended_at date/time will be 1 week after the started_at value.
  • ended_at (optional) (string) – Ending date/time for returned clips, in RFC3339 format. (Note that the seconds value is ignored.) If this is specified, started_at also must be specified; otherwise, the time period is ignored.
  • page_size (optional) (integer) – Number of objects returned in one call. Maximum: 100. Default: 20.
Returns:

APICursor if broadcaster_id or game_ids are provided, returns list of Clip objects instead.

For response fields of get_clips and official documentation check Twitch Helix Get Clips.

classmethod get_games(game_ids=None, names=None)

Gets game information by game ID or name.

Parameters:
  • game_ids (list) – List of Game IDs. At most 100 id values can be specified.
  • names (list) – List of Game names. 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.
Returns:

APICursor containing Game objects

For response fields of get_games and official documentation check Twitch Helix Get Games.

classmethod get_streams(after=None, before=None, community_ids=None, page_size=20, game_ids=None, languages=None, stream_type=None, user_ids=None, user_logins=None)

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.

Parameters:
  • after (string) – Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response.
  • before (string) – Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response.
  • community_ids (list) – Returns streams in a specified community ID. You can specify up to 100 IDs.
  • page_size (integer) – Number of objects returned in one call. Maximum: 100. Default: 20.
  • game_ids (list) – Returns streams broadcasting a specified game ID. You can specify up to 100 IDs.
  • languages (list) – Stream language. You can specify up to 100 languages
  • user_ids (list) – Returns streams broadcast by one or more specified user IDs. You can specify up to 100 IDs.
  • user_logins (list) – Returns streams broadcast by one or more specified user login names. You can specify up to 100 names.
Returns:

APICursor containing Stream objects

For response fields of get_streams and official documentation check Twitch Helix Get Streams.

classmethod get_top_games(after=None, before=None, page_size=20)

Gets games sorted by number of current viewers on Twitch, most popular first.

Parameters:
  • after (string) – Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response.
  • before (string) – Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response.
  • page_size (integer) – Number of objects returned in one call. Maximum: 100. Default: 20.
Returns:

APICursor containing Game objects

For response fields of get_top_games and official documentation check Twitch Helix Get Top Games.

classmethod get_videos(video_ids=None, user_id=None, game_id=None, after=None, before=None, page_size=20, language=None, period=None, sort=None, video_type=None)

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

Parameters:
  • video_ids (list) – List of Video IDs. Limit: 100. If this is specified, you cannot use any of the optional query string parameters below.
  • user_id (string) – User ID who owns the videos.
  • game_id (int) – Game ID of the videos.
  • after (optional) (string) – Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response.
  • before (optional) (string) – Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response.
  • page_size (optional) (integer) – Number of objects returned in one call. Maximum: 100. Default: 20.
  • language (optional) (string) – Language of the video being queried.
  • period (optional) (string) – Period during which the video was created. Valid values: VIDEO_PERIODS. Default: VIDEO_PERIOD_ALL
  • sort (optional) (string) – Sort order of the videos. Valid values: VIDEO_SORTS. Default: VIDEO_SORT_TIME
  • type (optional) (string) – Type of video. Valid values: VIDEO_TYPES. Default: VIDEO_TYPE_ALL
Returns:

APICursor if user_id or game_id are provided, returns list of Video objects instead.

For response fields of get_videos and official documentation check Twitch Helix Get Videos.

classmethod get_streams_metadata(after=None, before=None, community_ids=None, page_size=20, game_ids=None, languages=None, stream_type=None, user_ids=None, user_logins=None)

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.

Parameters:
  • after (string) – Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response.
  • before (string) – Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response.
  • community_ids (list) – Returns streams in a specified community ID. You can specify up to 100 IDs.
  • page_size (integer) – Number of objects returned in one call. Maximum: 100. Default: 20.
  • game_ids (list) – Returns streams broadcasting a specified game ID. You can specify up to 100 IDs.
  • languages (list) – Stream language. You can specify up to 100 languages
  • user_ids (list) – Returns streams broadcast by one or more specified user IDs. You can specify up to 100 IDs.
  • user_logins (list) – Returns streams broadcast by one or more specified user login names. You can specify up to 100 names.
Returns:

APICursor containing StreamMetadata objects

For response fields of get_streams and official documentation check Twitch Helix Get Streams Metadata.

classmethod get_user_follows(after=None, page_size=20, from_id=None, to_id=None)

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

Parameters:
  • after (string) – Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response.
  • page_size (integer) – Number of objects returned in one call. Maximum: 100. Default: 20.
  • from_id (list) – User ID. The request returns information about users who are being followed by the from_id user.
  • to_id (list) – User ID. The request returns information about users who are following the to_id user.
Returns:

APICursor containing Follow objects

For response fields of get_streams and official documentation check Twitch Helix Get Users Follows.