twitchAPI.twitch

The Twitch API client

This is the base of this library, it handles authentication renewal, error handling and permission management.

Look at the Twitch API reference for a more detailed documentation on what each endpoint does.

Example Usage:

from twitchAPI.twitch import Twitch
from pprint import pprint
twitch = Twitch('my_app_key', 'my_app_secret')
# lets create a simple app authentication:
twitch.authenticate_app([])
pprint(twitch.get_users(logins=['your_twitch_username']))

Authentication

The Twitch API knows 2 different authentications. App and User Authentication. Which one you need (or if one at all) depends on what calls you want to use.

Its always good to get at least App authentication even for calls where you don’t need it since the rate limits are way better for authenticated calls.

App Authentication

App authentication is super simple, just do the following:

from twitchAPI.twitch import Twitch
twitch = Twitch('my_app_id', 'my_app_secret')
# add App authentication
twitch.authenticate_app([])

User Authentication

To get a user auth token, the user has to explicitly click “Authorize” on the twitch website. You can use various online services to generate a token or use my build in authenticator.

See twitchAPI.oauth for more info.

Class Documentation:

class twitchAPI.twitch.Twitch(app_id: str, app_secret: str)

Twitch API client

Parameters:
  • app_id (str) – Your app id
  • app_secret (str) – Your app secret
Variables:

auto_refresh_auth (bool) – If set to true, auto refresh the auth token once it expires.

Default: True

authenticate_app(scope: List[twitchAPI.types.AuthScope]) → None

Authenticate with a fresh generated app token

Parameters:scope (list[AuthScope]) – List of Authorization scopes to use
Raises:TwitchAuthorizationException – if the authentication fails
Returns:None
check_automod_status(broadcaster_id: str, msg_id: str, msg_text: str, user_id: str) → dict

Determines whether a string message meets the channel’s AutoMod requirements.

Requires User authentication with scope twitchAPI.types.AuthScope.MODERATION_READ

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#check-automod-status

Parameters:
  • broadcaster_id (str) – Provided broadcaster ID must match the user ID in the user auth token.
  • msg_id (str) – Developer-generated identifier for mapping messages to results.
  • msg_text (str) – Message text.
  • user_id (str) – User ID of the sender.
Raises:
Return type:

dict

create_clip(broadcaster_id: str, has_delay: bool = False) → dict

Creates a clip programmatically. This returns both an ID and an edit URL for the new clip.

Requires User authentication with scope twitchAPI.types.AuthScope.CLIPS_EDIT

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#create-clip

Parameters:
  • broadcaster_id (str) – Broadcaster ID of the stream from which the clip will be made.
  • has_delay (bool) – 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
Raises:
Return type:

dict

create_custom_reward(broadcaster_id: str, title: str, prompt: str, cost: int, is_enabled: Optional[bool] = True, background_color: Optional[str] = None, is_user_input_required: Optional[bool] = False, is_max_per_stream_enabled: Optional[bool] = False, max_per_stream: Optional[int] = None, is_max_per_user_per_stream_enabled: Optional[bool] = False, max_per_user_per_stream: Optional[int] = None, is_global_cooldown_enabled: Optional[bool] = False, global_cooldown_seconds: Optional[int] = None, should_redemptions_skip_request_queue: Optional[bool] = False) → dict

Creates a Custom Reward on a channel.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_REDEMPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#create-custom-rewards

Parameters:
  • broadcaster_id (str) – ID of the broadcaster, must be same as user_id of auth token
  • title (str) – The title of the reward
  • prompt (str) – The prompt for the viewer when they are redeeming the reward
  • cost (int) – The cost of the reward
  • is_enabled – Is the reward currently enabled, if false the reward won’t show up to viewers.
    Default: true
  • background_color (str) – Custom background color for the reward. Format: Hex with # prefix. Example: #00E5CB.
    Default: None
  • is_user_input_required (bool) – Does the user need to enter information when redeeming the reward.
    Default: false
  • is_max_per_stream_enabled (bool) – Whether a maximum per stream is enabled.
    Default: false
  • max_per_stream (int) – The maximum number per stream if enabled
    Default: None
  • is_max_per_user_per_stream_enabled (bool) – Whether a maximum per user per stream is enabled.
    Default: false
  • max_per_user_per_stream (int) – The maximum number per user per stream if enabled
    Default: None
  • is_global_cooldown_enabled (bool) – Whether a cooldown is enabled.
    Default: false
  • global_cooldown_seconds (int) – The cooldown in seconds if enabled
    Default: None
  • should_redemptions_skip_request_queue (bool) – Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status.
    Default: false
Raises:
Return type:

dict

create_entitlement_grants_upload_url(manifest_id: str) → dict

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.

Requires App authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#create-entitlement-grants-upload-url

Parameters:

manifest_id (str) – Unique identifier of the manifest file to be uploaded. Must be 1-64 characters.

Raises:
Return type:

dict

create_stream_marker(user_id: str, description: Optional[str] = None) → dict

Creates a marker in the stream of a user specified by user ID.

Requires User authentication with scope twitchAPI.types.AuthScope.USER_EDIT_BROADCAST

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#create-stream-marker

Parameters:
  • user_id (str) – ID of the broadcaster in whose live stream the marker is created.
  • description (str) – Description of or comments on the marker. Max length is 140 characters.
    Default: None
Raises:
Return type:

dict

create_user_follows(from_id: str, to_id: str, allow_notifications: Optional[bool] = False) → bool

Adds a specified user to the followers of a specified channel.

Requires User authentication with twitchAPI.types.AuthScope.USER_EDIT_FOLLOWS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#create-user-follows

Parameters:
  • from_id (str) – User ID of the follower
  • to_id (str) – ID of the channel to be followed by the user
  • allow_notifications (bool) – If true, the user gets email or push notifications (depending on the user’s notification settings) when the channel goes live.
    Default: False
Raises:
Return type:

bool

delete_custom_reward(broadcaster_id: str, reward_id: str)

Deletes a Custom Reward on a channel.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_REDEMPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#delete-custom-rewards

Parameters:
  • broadcaster_id (str) – Provided broadcaster_id must match the user_id in the auth token
  • reward_id (str) – ID of the Custom Reward to delete, must match a Custom Reward on broadcaster_id’s channel.
Raises:
delete_user_follows(from_id: str, to_id: str) → bool

Deletes a specified user from the followers of a specified channel.

Requires User authentication with twitchAPI.types.AuthScope.USER_EDIT_FOLLOWS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#delete-user-follows

Parameters:
  • from_id (str) – User ID of the follower
  • to_id (str) – Channel to be unfollowed by the user
Raises:
Return type:

bool

get_all_stream_tags(after: Optional[str] = None, first: int = 20, tag_ids: Optional[List[str]] = None) → dict

Gets the list of all stream tags defined by Twitch, optionally filtered by tag ID(s).

Requires App authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-all-stream-tags

Parameters:
  • after (str) – Cursor for forward pagination
    Default: None
  • first (int) – Maximum number of objects to return. Maximum: 100.
    Default: 20
  • tag_ids (list[str]) – IDs of tags. Maximum 100 entries
    Default: None
Raises:
Return type:

dict

get_app_token() → Optional[str]

Returns the app token that the api uses or None when not authenticated.

Returns:app token
Return type:Union[str, None]
get_banned_events(broadcaster_id: str, user_id: Optional[str] = None, after: Optional[str] = None, first: int = 20) → dict

Returns all user bans and un-bans in a channel.

Requires User authentication with scope twitchAPI.types.AuthScope.MODERATION_READ

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-banned-events

Parameters:
  • broadcaster_id (str) – Provided broadcaster ID must match the user ID in the user auth token.
  • user_id (str) – Filters the results and only returns a status object for users who are banned in this channel and have a matching user_id
    Default: None
  • after (str) – Cursor for forward pagination
    Default: None
  • first (int) – Maximum number of objects to return. Maximum: 100.
    Default: 20
Raises:
Return type:

dict

get_banned_users(broadcaster_id: str, user_id: Optional[str] = None, after: Optional[str] = None, first: Optional[int] = 20, before: Optional[str] = None) → dict

Returns all banned and timed-out users in a channel.

Requires User authentication with scope twitchAPI.types.AuthScope.MODERATION_READ

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-banned-users

Parameters:
  • broadcaster_id (str) – Provided broadcaster ID must match the user ID in the user auth token.
  • user_id (str) – Filters the results and only returns a status object for users who are banned in this channel and have a matching user_id.
    Default: None
  • after (str) – Cursor for forward pagination
    Default: None
  • before (str) – Cursor for backward pagination
    Default: None
  • first (int) – Maximum number of objects to return. Maximum: 100.
    Default: 20
Raises:
Return type:

dict

get_bits_leaderboard(count: int = 10, period: twitchAPI.types.TimePeriod = <TimePeriod.ALL: 'all'>, started_at: Optional[datetime.datetime] = None, user_id: Optional[str] = None) → dict

Gets a ranked list of Bits leaderboard information for an authorized broadcaster.

Requires User authentication with scope twitchAPI.types.AuthScope.BITS_READ

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-bits-leaderboard

Parameters:
  • count (int) – Number of results to be returned. In range 1 to 100,
    Default: 10
  • period (TimePeriod) – Time period over which data is aggregated,
    Default: twitchAPI.types.TimePeriod.ALL
  • started_at (datetime) – Timestamp for the period over which the returned data is aggregated.
    Default: None
  • user_id (str) – ID of the user whose results are returned; i.e., the person who paid for the Bits.
    Default: None
Raises:
Return type:

dict

get_broadcaster_subscriptions(broadcaster_id: str, user_ids: Optional[List[str]] = None, after: Optional[str] = None, first: Optional[int] = 20) → dict

Get all of a broadcaster’s subscriptions.

Requires User authentication with scope twitchAPI.types.AuthScope.CHANNEL_READ_SUBSCRIPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-broadcaster-subscriptions

Parameters:
  • broadcaster_id (str) – User ID of the broadcaster. Must match the User ID in the Bearer token.
  • user_ids (list[str]) – Unique identifier of account to get subscription status of. Maximum 100 entries
    Default: None
  • after (str) – Cursor for forward pagination.
    Default: None
  • first (int) – Maximum number of objects to return. Maximum: 100.
    Default: 20
Raises:
Return type:

dict

get_channel_information(broadcaster_id: str) → dict

Gets channel information for users.

Requires App or user authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-channel-information

Parameters:

broadcaster_id (str) – ID of the channel to be updated

Raises:
Return type:

dict

get_cheermotes(broadcaster_id: str) → dict

Retrieves the list of available Cheermotes, animated emotes to which viewers can assign Bits, to cheer in chat.

Requires App authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-cheermotes

Parameters:

broadcaster_id (str) – ID for the broadcaster who might own specialized Cheermotes.

Raises:
Return type:

dict

get_clips(broadcaster_id: Optional[str] = None, game_id: Optional[str] = None, clip_id: Optional[List[str]] = None, after: Optional[str] = None, before: Optional[str] = None, ended_at: Optional[datetime.datetime] = None, started_at: Optional[datetime.datetime] = None, first: int = 20) → dict

Gets clip information by clip ID (one or more), broadcaster ID (one only), or game ID (one only). Clips are returned sorted by view count, in descending order.

Requires App or User authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-clips

Parameters:
  • broadcaster_id (str) – ID of the broadcaster for whom clips are returned.
    Default: None
  • game_id (str) – ID of the game for which clips are returned.
    Default: None
  • clip_id (list[str]) – ID of the clip being queried. Limit: 100.
    Default: None
  • first (int) – Maximum number of objects to return. Maximum: 100.
    Default: 20
  • after (str) – Cursor for forward pagination
    Default: None
  • before (str) – Cursor for backward pagination
    Default: None
  • ended_at (datetime) – Ending date/time for returned clips
    Default: None
  • started_at (datetime) – Starting date/time for returned clips
    Default: None
Raises:
Return type:

dict

get_code_status(code: List[str], user_id: int) → dict

Gets the status of one or more provided Bits codes.

Requires App authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-code-status

Parameters:
  • code (list[str]) – The code to get the status of. Maximum of 20 entries
  • user_id (int) – Represents the numeric Twitch user ID of the account which is going to receive the entitlement associated with the code.
Raises:
Return type:

dict

get_custom_reward(broadcaster_id: str, reward_id: Optional[List[str]] = None, only_manageable_rewards: Optional[bool] = False) → dict

Returns a list of Custom Reward objects for the Custom Rewards on a channel. Developers only have access to update and delete rewards that the same/calling client_id created.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_READ_REDEMPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-custom-reward

Parameters:
  • broadcaster_id (str) – Provided broadcaster_id must match the user_id in the auth token
  • reward_id (list[str]) – When used, this parameter filters the results and only returns reward objects for the Custom Rewards with matching ID. Maximum: 50
    Default: None
  • only_manageable_rewards (bool) – When set to true, only returns custom rewards that the calling client_id can manage.
    Default: false
Return type:

dict

Raises:
get_custom_reward_redemption(broadcaster_id: str, reward_id: str, id: Optional[List[str]] = None, status: Optional[twitchAPI.types.CustomRewardRedemptionStatus] = None, sort: Optional[twitchAPI.types.SortOrder] = <SortOrder.OLDEST: 'OLDEST'>, after: Optional[str] = None, first: Optional[int] = 20) → dict

Returns Custom Reward Redemption objects for a Custom Reward on a channel that was created by the same client_id.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_READ_REDEMPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-custom-reward-redemption

Parameters:
  • broadcaster_id (str) – Provided broadcaster_id must match the user_id in the auth token
  • reward_id (str) – When ID is not provided, this parameter returns paginated Custom Reward Redemption objects for redemptions of the Custom Reward with ID reward_id
  • id (list(str)) – When used, this param filters the results and only returns
    Default: None Custom Reward Redemption objects for the redemptions with matching ID. Maximum: 50 ids
    Default: None
  • status (CustomRewardRedemptionStatus) – When id is not provided, this param is required and filters the paginated Custom Reward Redemption objects for redemptions with the matching status.
    Default: None
  • sort (SortOrder) – Sort order of redemptions returned when getting the paginated Custom Reward Redemption objects for a reward.
    Default: SortOrder.OLDEST
  • after (str) – Cursor for forward pagination.
    Default: None
  • first (int) – Number of results to be returned when getting the paginated Custom Reward Redemption objects for a reward. Limit: 50
    Default: 20
Return type:

dict

Raises:
get_drops_entitlements(id: Optional[str] = None, user_id: Optional[str] = None, game_id: Optional[str] = None, after: Optional[str] = None, first: Optional[int] = 20) → dict

Gets a list of entitlements for a given organization that have been granted to a game, user, or both.

OAuth Token Client ID must have ownership of Game

Requires App authentication

See Twitch documentation for valid parameter combinations!

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-drops-entitlements

Parameters:
  • id (str) – Unique Identifier of the entitlement
    Default: None
  • user_id (str) – A Twitch User ID
    Default: None
  • game_id (str) – A Twitch Game ID
    Default: None
  • after (str) – The cursor used to fetch the next page of data.
    Default: None
  • first (int) – Maximum number of entitlements to return. Maximum: 100
    Default: 20
Raises:
Return type:

dict

get_extension_analytics(after: Optional[str] = None, extension_id: Optional[str] = None, first: int = 20, ended_at: Optional[datetime.datetime] = None, started_at: Optional[datetime.datetime] = None, report_type: Optional[twitchAPI.types.AnalyticsReportType] = None) → dict

Gets a URL that extension developers can use to download analytics reports (CSV files) for their extensions. The URL is valid for 5 minutes.

Requires User authentication with scope twitchAPI.types.AuthScope.ANALYTICS_READ_EXTENSION

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-extension-analytics

Parameters:
  • after (str) – cursor for forward pagination
    Default: None
  • extension_id (str) – If this is specified, the returned URL points to an analytics report for just the specified extension.
    Default: None
  • first (int) – Maximum number of objects returned, range 1 to 100,
    Default: 20
  • ended_at (datetime) – Ending date/time for returned reports, if this is provided, started_at must also be specified.
    Default: None
  • started_at (datetime) – Starting date/time for returned reports, if this is provided, ended_at must also be specified.
    Default: None
  • report_type (AnalyticsReportType) – Type of analytics report that is returned
    Default: None
Return type:

dict

Raises:
get_extension_transactions(extension_id: str, transaction_id: Optional[str] = None, after: Optional[str] = None, first: int = 20) → dict

Get Extension Transactions allows extension back end servers to fetch a list of transactions that have occurred for their extension across all of Twitch. A transaction is a record of a user exchanging Bits for an in-Extension digital good.

Requires App authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-extension-transactions

Parameters:
  • extension_id (str) – ID of the extension to list transactions for.
  • transaction_id (str) – Transaction IDs to look up.
    Default: None
  • after (str) – cursor for forward pagination
    Default: None
  • first (int) – Maximum number of objects returned, range 1 to 100,
    Default: 20
Raises:
Return type:

dict

get_game_analytics(after: Optional[str] = None, first: int = 20, game_id: Optional[str] = None, ended_at: Optional[datetime.datetime] = None, started_at: Optional[datetime.datetime] = None, report_type: Optional[twitchAPI.types.AnalyticsReportType] = None) → dict

Gets a URL that game developers can use to download analytics reports (CSV files) for their games. The URL is valid for 5 minutes.

Requires User authentication with scope twitchAPI.types.AuthScope.ANALYTICS_READ_GAMES

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-game-analytics

Parameters:
  • after (str) – cursor for forward pagination
    Default: None
  • first (int) – Maximum number of objects returned, range 1 to 100,
    Default: 20
  • game_id (str) – Game ID
    Default: None
  • ended_at (datetime) – Ending date/time for returned reports, if this is provided, started_at must also be specified.
    Default: None
  • started_at (datetime) – Starting date/time for returned reports, if this is provided, ended_at must also be specified.
    Default: None
  • report_type (AnalyticsReportType) – Type of analytics report that is returned.
    Default: None
Raises:
Return type:

dict

get_games(game_ids: Optional[List[str]] = None, names: Optional[List[str]] = None) → dict

Gets game information by game ID or name.

Requires User or App authentication. In total, only 100 game ids and names can be fetched at once.

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-games

Parameters:
  • game_ids (list[str]) – Game ID
    Default: None
  • names (list[str]) – Game Name
    Default: None
Raises:
Return type:

dict

get_hype_train_events(broadcaster_id: str, first: Optional[int] = 1, id: Optional[str] = None, cursor: Optional[str] = None) → dict

Gets the information of the most recent Hype Train of the given channel ID. When there is currently an active Hype Train, it returns information about that Hype Train. When there is currently no active Hype Train, it returns information about the most recent Hype Train. After 5 days, if no Hype Train has been active, the endpoint will return an empty response.

Requires App or User authentication with twitchAPI.types.AuthScope.CHANNEL_READ_HYPE_TRAIN

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-hype-train-events

Parameters:
  • broadcaster_id (str) – User ID of the broadcaster.
  • first (int) – Maximum number of objects to return. Maximum: 100.
    Default: 1
  • id (str) – The id of the wanted event, if known
    Default: None
  • cursor (str) – Cursor for forward pagination
    Default: None
Raises:
Return type:

dict

get_moderator_events(broadcaster_id: str, user_ids: Optional[List[str]] = None, after: Optional[str] = None, first: Optional[int] = 20) → dict

Returns a list of moderators or users added and removed as moderators from a channel.

Requires User authentication with scope twitchAPI.types.AuthScope.MODERATION_READ

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-moderator-events

Parameters:
  • broadcaster_id (str) – Provided broadcaster ID must match the user ID in the user auth token.
  • user_ids (list[str]) – Filters the results and only returns a status object for users who are moderator in this channel and have a matching user_id. Maximum 100
    Default: None
  • after (str) – Cursor for forward pagination
    Default: None
  • first (int) – Maximum number of objects to return. Maximum: 100.
    Default: 20
Raises:
Return type:

dict

get_moderators(broadcaster_id: str, user_ids: Optional[List[str]] = None, first: Optional[int] = 20, after: Optional[str] = None) → dict

Returns all moderators in a channel.

Requires User authentication with scope twitchAPI.types.AuthScope.MODERATION_READ

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-moderators

Parameters:
  • broadcaster_id (str) – Provided broadcaster ID must match the user ID in the user auth token.
  • user_ids (list[str]) – Filters the results and only returns a status object for users who are moderator in this channel and have a matching user_id. Maximum 100
    Default: None
  • after (str) – Cursor for forward pagination
    Default: None
  • first (int) – Maximum number of objects to return. Maximum: 100.
    Default: 20
Raises:
Return type:

dict

get_stream_key(broadcaster_id: str) → dict

Gets the channel stream key for a user.

Requires User authentication with twitchAPI.types.AuthScope.CHANNEL_READ_STREAM_KEY

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-stream-key

Parameters:

broadcaster_id (str) – User ID of the broadcaster

Raises:
Return type:

dict

get_stream_markers(user_id: str, video_id: str, after: Optional[str] = None, before: Optional[str] = None, first: int = 20) → dict

Gets a list of markers for either a specified user’s most recent stream or a specified VOD/video (stream), ordered by recency.

Requires User authentication with scope twitchAPI.types.AuthScope.USER_READ_BROADCAST

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-stream-markers

Only one of user_id and video_id must be specified.

Parameters:
  • user_id (str) – ID of the broadcaster from whose stream markers are returned.
  • video_id (str) – ID of the VOD/video whose stream markers are returned.
  • after (str) – Cursor for forward pagination
    Default: None
  • before (str) – Cursor for backward pagination
    Default: None
  • first (int) – Number of values to be returned when getting videos by user or game ID. Limit: 100.
    Default: 20
Raises:
Return type:

dict

get_stream_tags(broadcaster_id: str) → dict

Gets the list of tags for a specified stream (channel).

Requires App authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-stream-tags

Parameters:

broadcaster_id (str) – ID of the stream that’s tags are going to be fetched

Raises:
Return type:

dict

get_streams(after: Optional[str] = None, before: Optional[str] = None, first: int = 20, game_id: Optional[List[str]] = None, language: Optional[List[str]] = None, user_id: Optional[List[str]] = None, user_login: Optional[List[str]] = None) → dict

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.

Requires App or User authentication.

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-streams

Parameters:
  • after (str) – Cursor for forward pagination
    Default: None
  • before (str) – Cursor for backward pagination
    Default: None
  • first (int) – Maximum number of objects to return. Maximum: 100.
    Default: 20
  • game_id (list[str]) – Returns streams broadcasting a specified game ID. You can specify up to 100 IDs.
    Default: None
  • language (list[str]) – Stream language. You can specify up to 100 languages.
    Default: None
  • user_id (list[str]) – Returns streams broadcast by one or more specified user IDs. You can specify up to 100 IDs.
    Default: None
  • user_login (list[str]) – Returns streams broadcast by one or more specified user login names. You can specify up to 100 names.
    Default: None
Raises:
Return type:

dict

get_top_games(after: Optional[str] = None, before: Optional[str] = None, first: int = 20) → dict

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

Requires App or User authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-top-games

Parameters:
  • after (str) – Cursor for forward pagination
    Default: None
  • before (str) – Cursor for backward pagination
    Default: None
  • first (int) – Maximum number of objects to return. Maximum: 100.
    Default: 20
Raises:
Return type:

dict

get_used_token() → Optional[str]

Returns the currently used token, can be either the app or user auth Token or None if no auth is set

Returns:the currently used auth token or None if no Authentication is set
get_user_active_extensions(user_id: Optional[str] = None) → dict

Gets information about active extensions installed by a specified user, identified by a user ID or the authenticated user.

Requires User authentication with scope twitchAPI.types.AuthScope.USER_READ_BROADCAST

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-user-active-extensions

Parameters:

user_id (str) – ID of the user whose installed extensions will be returned.

Default: None

Raises:
Return type:

dict

get_user_auth_scope() → List[twitchAPI.types.AuthScope]

Returns the set User auth Scope

get_user_auth_token() → Optional[str]

Returns the current user auth token, None if no user Authentication is set

Returns:current user auth token
Return type:str or None
get_user_extensions() → dict

Gets a list of all extensions (both active and inactive) for the authenticated user

Requires User authentication with scope twitchAPI.types.AuthScope.USER_READ_BROADCAST

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-user-extensions

Raises:
Return type:

dict

get_users(user_ids: Optional[List[str]] = None, logins: Optional[List[str]] = None) → dict

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 the one authenticated.

Requires App authentication if either user_ids or logins is provided, otherwise requires a User authentication. If you have user Authentication and want to get your email info, you also need the authentication scope twitchAPI.types.AuthScope.USER_READ_EMAIL

If you provide user_ids and/or logins, the maximum combined entries should not exceed 100.

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-users

Parameters:
  • user_ids (list[str]) – User ID. Multiple user IDs can be specified. Limit: 100.
    Default: None
  • logins (list[str]) – User login name. Multiple login names can be specified. Limit: 100.
    Default: None
Raises:
Return type:

dict

get_users_follows(after: Optional[str] = None, first: int = 20, from_id: Optional[str] = None, to_id: Optional[str] = None) → dict

Gets information on follow relationships between two Twitch users. Information returned is sorted in order, most recent follow first.

Requires App authentication.

You have to use at least one of the following fields: from_id, to_id For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-users-follows

Parameters:
  • after (str) – Cursor for forward pagination
    Default: None
  • first (int) – Maximum number of objects to return. Maximum: 100.
    Default: 20
  • from_id (str) – User ID. The request returns information about users who are being followed by the from_id user.
    Default: None
  • to_id (str) – User ID. The request returns information about users who are following the to_id user.
    Default: None
Raises:
Return type:

dict

get_videos(ids: Optional[List[str]] = None, user_id: Optional[str] = None, game_id: Optional[str] = None, after: Optional[str] = None, before: Optional[str] = None, first: Optional[int] = 20, language: Optional[str] = None, period: twitchAPI.types.TimePeriod = <TimePeriod.ALL: 'all'>, sort: twitchAPI.types.SortMethod = <SortMethod.TIME: 'time'>, video_type: twitchAPI.types.VideoType = <VideoType.ALL: 'all'>) → dict

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

Requires App authentication.

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-videos

Parameters:
  • ids (list[str]) – ID of the video being queried. Limit: 100.
    Default: None
  • user_id (str) – ID of the user who owns the video.
    Default: None
  • game_id (str) – ID of the game the video is of.
    Default: None
  • after (str) – Cursor for forward pagination
    Default: None
  • before (str) – Cursor for backward pagination
    Default: None
  • first (int) – Number of values to be returned when getting videos by user or game ID. Limit: 100.
    Default: 20
  • language (str) – Language of the video being queried.
    Default: None
  • period (TimePeriod) – Period during which the video was created.
    Default: TimePeriod.ALL
  • sort (SortMethod) – Sort order of the videos.
    Default: SortMethod.TIME
  • video_type (VideoType) – Type of video.
    Default: VideoType.ALL
Raises:
Return type:

dict

get_webhook_subscriptions(first: Optional[int] = 20, after: Optional[str] = None) → dict

Gets the Webhook subscriptions of the authenticated user, in order of expiration.

Requires App authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-webhook-subscriptions

Parameters:
  • first (int) – Number of values to be returned per page. Limit: 100.
    Default: 20
  • after (str) – Cursor for forward pagination
    Default: None
Raises:
Return type:

dict

modify_channel_information(broadcaster_id: str, game_id: Optional[str] = None, broadcaster_language: Optional[str] = None, title: Optional[str] = None) → bool

Modifies channel information for users.

Requires User authentication with scope twitchAPI.types.AuthScope.USER_EDIT_BROADCAST

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#modify-channel-information

Parameters:
  • broadcaster_id (str) – ID of the channel to be updated
  • game_id (str) – The current game ID being played on the channel
    Default: None
  • broadcaster_language (str) – The language of the channel
    Default: None
  • title (str) – The title of the stream
    Default: None
Raises:
Return type:

bool

redeem_code(code: List[str], user_id: int) → dict

Redeems one or more provided Bits codes to the authenticated Twitch user.

Requires App authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#redeem-code

Parameters:
  • code (list[str]) – The code to redeem to the authenticated user’s account. Maximum of 20 entries
  • user_id (int) – Represents the numeric Twitch user ID of the account which is going to receive the entitlement associated with the code.
Raises:
Return type:

dict

refresh_used_token()

Refreshes the currently used token

replace_stream_tags(broadcaster_id: str, tag_ids: List[str]) → dict

Applies specified tags to a specified stream, overwriting any existing tags applied to that stream. If no tags are specified, all tags previously applied to the stream are removed. Automated tags are not affected by this operation.

Requires User authentication with scope twitchAPI.types.AuthScope.USER_EDIT_BROADCAST

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#replace-stream-tags

Parameters:
  • broadcaster_id (str) – ID of the stream for which tags are to be replaced.
  • tag_ids (list[str]) – IDs of tags to be applied to the stream. Maximum of 100 supported.
Returns:

{}

Raises:
Return type:

dict

search_categories(query: str, first: Optional[int] = 20, after: Optional[str] = None) → dict

Returns a list of games or categories that match the query via name either entirely or partially.

Requires App authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#search-categories

Parameters:
  • query (str) – search query
  • first (int) – Maximum number of objects to return. Maximum: 100
    Default: 20
  • after (str) – Cursor for forward pagination
    Default: None
Raises:
Return type:

dict

search_channels(query: str, first: Optional[int] = 20, after: Optional[str] = None, live_only: Optional[bool] = False) → dict

Returns a list of channels (users who have streamed within the past 6 months) that match the query via channel name or description either entirely or partially.

Requires App authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#search-channels

Parameters:
  • query (str) – search query
  • first (int) – Maximum number of objects to return. Maximum: 100
    Default: 20
  • after (str) – Cursor for forward pagination
    Default: None
  • live_only (bool) – Filter results for live streams only.
    Default: False
Raises:
Return type:

dict

set_user_authentication(token: str, scope: List[twitchAPI.types.AuthScope], refresh_token: Optional[str] = None)

Set a user token to be used.

Parameters:
  • token (str) – the generated user token
  • scope (list[AuthScope]) – List of Authorization Scopes that the given user token has
  • refresh_token (str) – The generated refresh token, has to be provided if auto_refresh_auth is True
    Default: None
Raises:

ValueError – if auto_refresh_auth is True but refresh_token is not set

start_commercial(broadcaster_id: str, length: int) → dict

Starts a commercial on a specified channel.

Requires User authentication with twitchAPI.types.AuthScope.CHANNEL_EDIT_COMMERCIAL

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#start-commercial

Parameters:
  • broadcaster_id (str) – ID of the channel requesting a commercial
  • length (int) – Desired length of the commercial in seconds. , one of these: [30, 60, 90, 120, 150, 180]
Raises:
Return type:

dict

update_custom_reward(broadcaster_id: str, reward_id: str, title: str, prompt: str, cost: int, is_enabled: Optional[bool] = True, background_color: Optional[str] = None, is_user_input_required: Optional[bool] = False, is_max_per_stream_enabled: Optional[bool] = False, max_per_stream: Optional[int] = None, is_max_per_user_per_stream_enabled: Optional[bool] = False, max_per_user_per_stream: Optional[int] = None, is_global_cooldown_enabled: Optional[bool] = False, global_cooldown_seconds: Optional[int] = None, should_redemptions_skip_request_queue: Optional[bool] = False) → dict

Updates a Custom Reward created on a channel.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_REDEMPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-custom-rewards

Parameters:
  • broadcaster_id (str) – ID of the broadcaster, must be same as user_id of auth token
  • reward_id (str) – ID of the reward that you want to update
  • title (str) – The title of the reward
  • prompt (str) – The prompt for the viewer when they are redeeming the reward
  • cost (int) – The cost of the reward
  • is_enabled – Is the reward currently enabled, if false the reward won’t show up to viewers.
    Default: true
  • background_color (str) – Custom background color for the reward.
    Default: None Format: Hex with # prefix. Example: #00E5CB.
  • is_user_input_required (bool) – Does the user need to enter information when redeeming the reward.
    Default: false
  • is_max_per_stream_enabled (bool) – Whether a maximum per stream is enabled.
    Default: false
  • max_per_stream (int) – The maximum number per stream if enabled
    Default: None
  • is_max_per_user_per_stream_enabled (bool) – Whether a maximum per user per stream is enabled.
    Default: false
  • max_per_user_per_stream (int) – The maximum number per user per stream if enabled
    Default: None
  • is_global_cooldown_enabled (bool) – Whether a cooldown is enabled.
    Default: false
  • global_cooldown_seconds (int) – The cooldown in seconds if enabled
    Default: None
  • should_redemptions_skip_request_queue (bool) – Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status.
    Default: false
Raises:
  • TwitchAPIException – if the request was malformed
  • ValueError – if is_global_cooldown_enabled is True but global_cooldown_seconds is not specified
  • ValueError – if is_max_per_stream_enabled is True but max_per_stream is not specified
  • ValueError – if is_max_per_user_per_stream_enabled is True but max_per_user_per_stream is not specified
  • UnauthorizedException – if user authentication is not set or invalid
  • MissingScopeException – if the user authentication is missing the required scope
  • TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
  • TwitchBackendException – if the Twitch API itself runs into problems
  • TwitchAPIException – if a Query Parameter is missing or invalid
  • TwitchAPIException – if Channel Points are not available for the broadcaster or the custom reward belongs to a different broadcaster
  • ValueError – if the given reward_id does not match a custom reward by the given broadcaster
Return type:

dict

update_redemption_status(broadcaster_id: str, reward_id: str, redemption_ids: List[str], status: twitchAPI.types.CustomRewardRedemptionStatus) → dict
Updates the status of Custom Reward Redemption objects on a channel that
are in the UNFULFILLED status.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_REDEMPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-redemption-status

Parameters:
  • broadcaster_id (str) – Provided broadcaster_id must match the user_id in the auth token.
  • reward_id (str) – ID of the Custom Reward the redemptions to be updated are for.
  • redemption_ids (list(str)) – IDs of the Custom Reward Redemption to update, must match a Custom Reward Redemption on broadcaster_id’s channel Max: 50
  • status (CustomRewardRedemptionStatus) – The new status to set redemptions to.
Raises:
Return type:

dict

update_user(description: str) → dict

Updates the description of the Authenticated user.

Requires User authentication with scope twitchAPI.types.AuthScope.USER_EDIT

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-user

Parameters:

description (str) – User’s account description

Raises:
Return type:

dict

update_user_extensions(data: dict) → dict

“Updates the activation state, extension ID, and/or version number of installed extensions for the authenticated user.

Requires User authentication with scope twitchAPI.types.AuthScope.USER_EDIT_BROADCAST

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-user-extensions

Parameters:

data (dict) – The user extension data to be written

Raises:
Return type:

dict