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: 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: Raises: - TwitchAPIException – if the request was malformed
- 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
Return type:
-
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: - TwitchAPIException – if the request was malformed
- 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
Return type:
-
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
- background_color (str) – Custom background color for the reward. Format: Hex with # prefix. Example:
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
Return type:
-
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: - UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the the authentication token became invalid and a re authentication failed
- TwitchAPIException – if the request was malformed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if length of manifest_id is not in range 1 to 64
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- 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
- ValueError – if description has more than 140 characters
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- 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
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- 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
- NotFoundException – if the broadcaster has no custom reward with the given id
-
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: Raises: - TwitchAPIException – if the request was malformed
- 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
Return type:
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
Raises: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if first is not in range 1 to 100 or tag_ids has more than 100 entries
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- 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
- ValueError – if first is not in range 1 ot 100
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- 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
- ValueError – if first is not in range 1 to 100
Return type:
-
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,
Raises: - 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
- TwitchAPIException – if the request was malformed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if first is not in range 1 to 100
Return type:
-
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: Raises: - 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
- TwitchAPIException – if the request was malformed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if user_ids has more than 100 entries
- ValueError – if first is not in range 1 to 100
Return type:
-
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: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
Return type:
-
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: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
Return type:
-
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.
Raises: - UnauthorizedException – if user authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if you try to query more than 100 clips in one call
- TwitchAPIException – if the request was malformed
- ValueError – if not exactly one of clip_id, broadcaster_id or game_id is given
- ValueError – if first is not in range 1 to 100
Return type:
-
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: Raises: - UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchAPIException – if the request was malformed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if length of code is not in range 1 to 20
Return type:
-
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
- only_manageable_rewards (bool) – When set to true, only returns custom rewards that the calling client_id can manage.
Return type: Raises: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- MissingScopeException – if the user or app 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
- ValueError – if if reward_id is longer than 50 entries
-
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 idsDefault: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.
- 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.
Return type: Raises: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- MissingScopeException – if the user or app 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
- ValueError – if id has more than 50 entries
- ValueError – if first is not in range 1 to 50
-
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
Raises: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if first is not in range 1 to 100
Return type:
-
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
- extension_id (str) – If this is specified, the returned URL points to an analytics report for just the specified extension.
Return type: Raises: - 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
- TwitchAPIException – if the request was malformed and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – When you only supply started_at or ended_at without the other or when first is not in range 1 to 100
- after (str) – cursor for forward pagination
-
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: Raises: - UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchAPIException – if the request was malformed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if first is not in range 1 to 100
Return type:
-
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
- first (int) – Maximum number of objects returned, range 1 to 100,
Raises: - 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
- TwitchAPIException – if the request was malformed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – When you only supply started_at or ended_at without the other or when first is not in range 1 to 100
Return type: - after (str) – cursor for forward pagination
-
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: Raises: - UnauthorizedException – if app authentication is not set or invalid
- TwitchAPIException – if the request was malformed
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if neither game_ids nor names are given or if game_ids and names are more than 100 entries combined.
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- MissingScopeException – if the user or app 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
- ValueError – if first is not in range 1 to 100
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- 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
- ValueError – if user_ids has more than 100 entries
- ValueError – if first is not in range 1 to 100
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- 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
- ValueError – if user_ids has more than 100 entries
- ValueError – if first is not in range 1 to 100
Return type:
-
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: - TwitchAPIException – if the request was malformed
- 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
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- 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
- ValueError – if first is not in range 1 to 100 or neither user_id nor video_id is provided
Return type:
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: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if first is not in range 1 to 100 or one of the following fields have more than 100 entries: user_id, game_id, language, user_login
Return type:
-
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
Raises: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if first is not in range 1 to 100
Return type:
-
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: - TwitchAPIException – if the request was malformed
- 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
Return type:
-
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: - TwitchAPIException – if the request was malformed
- 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
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- 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
- ValueError – if more than 100 combined user_ids and logins where provided
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if first is not in range 1 to 100 or neither from_id nor to_id is provided
Return type:
-
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.
- user_id (str) – ID of the user who owns the video.
Raises: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if first is not in range 1 to 100, ids has more than 100 entries or none of ids, user_id nor game_id is provided.
Return type: - ids (list[str]) – ID of the video being queried. Limit: 100.
-
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.
Raises: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if first is not in range 1 to 100
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- 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
- ValueError – if none of the following fiends are specified: game_id, broadcaster_language, title
Return type:
-
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: Raises: - UnauthorizedException – if app authentication is not set or invalid
- TwitchAPIException – if the request was malformed
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if length of code is not in range 1 to 20
Return type:
-
refresh_used_token
()¶ Refreshes the currently used token
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: Returns: {}
Raises: - TwitchAPIException – if the request was malformed
- 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
- ValueError – if more than 100 tag_ids where provided
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if first is not in range 1 to 100
Return type:
-
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: Raises: - TwitchAPIException – if the request was malformed
- UnauthorizedException – if app authentication is not set or invalid
- TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
- TwitchBackendException – if the Twitch API itself runs into problems
- ValueError – if first is not in range 1 to 100
Return type:
-
set_user_authentication
(token: str, scope: List[twitchAPI.types.AuthScope], refresh_token: Optional[str] = None)¶ Set a user token to be used.
Parameters: 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: Raises: - TwitchAPIException – if the request was malformed
- 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
- ValueError – if length is not one of these: 30, 60, 90, 120, 150, 180
Return type:
-
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
- background_color (str) – Custom background color for the reward.
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:
-
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: - TwitchAPIException – if the request was malformed
- 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 redemption_ids is longer than 50 entries
- ValueError – if no custom reward redemptions with status UNFULFILLED where found for the given ids
- TwitchAPIException – if Channel Points are not available for the broadcaster or the custom reward belongs to a different broadcaster
Return type:
-
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: - TwitchAPIException – if the request was malformed
- 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
Return type:
-
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: - TwitchAPIException – if the request was malformed
- 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
Return type:
-