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')
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¶
By default, The lib will try to attempt to create a App Authentication on Initialization:
from twitchAPI.twitch import Twitch
twitch = Twitch('my_app_id', 'my_app_secret')
You can set a Auth Scope like this:
from twitchAPI.twitch import Twitch, AuthScope
twitch = Twitch('my_app_id', 'my_app_secret', target_app_auth_scope=[AuthScope.USER_EDIT])
If you want to change the AuthScope later use this:
twitch.authenticate_app(my_new_scope)
If you don’t want to use App Authentication, Initialize like this:
from twitchAPI.twitch import Twitch
twitch = Twitch('my_app_id', authenticate_app=False)
User Authentication¶
Only use a user auth token, use this:
from twitchAPI.twitch import Twitch
twitch = Twitch('my_app_id', authenticate_app=False)
# make sure to set the second parameter as the scope used to generate the token
twitch.set_user_authentication('token', [], 'refresh_token')
Use both App and user Authentication:
from twitchAPI.twitch import Twitch
twitch = Twitch('my_app_id', 'my_app_secret')
# make sure to set the second parameter as the scope used to generate the token
twitch.set_user_authentication('token', [], 'refresh_token')
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 on my build in authenticator.
Authentication refresh callback¶
Optionally you can set a callback for both user access token refresh and app access token refresh.
from twitchAPI.twitch import Twitch
def user_refresh(token: str, refresh_token: str):
print(f'my new user token is: {token}')
def app_refresh(token: str):
print(f'my new app token is: {token}')
twitch = Twitch('my_app_id', 'my_app_secret')
twitch.app_auth_refresh_callback = app_refresh
twitch.user_auth_refresh_callback = user_refresh
Class Documentation:¶
- class twitchAPI.twitch.Twitch(app_id: str, app_secret: Optional[str] = None, authenticate_app: bool = True, target_app_auth_scope: Optional[List[twitchAPI.types.AuthScope]] = None)¶
Twitch API client
- Parameters
app_id (str) – Your app id
app_secret (str) – Your app secret, leave as None if you only want to use User Authentication
Default:None
authenticate_app (bool) – If true, auto generate a app token on startup
Default:True
target_app_auth_scope (list[AuthScope]) – AuthScope to use if
authenticate_app
is TrueDefault:None
- Variables
auto_refresh_auth (bool) – If set to true, auto refresh the auth token once it expires.
Default:True
user_auth_refresh_callback (Callable[[str,str],None]) – If set, gets called whenever a user auth token gets refreshed. Parameter: Auth Token, Refresh Token
Default:None
app_auth_refresh_callback (Callable[[str,str],None]) – If set, gets called whenever a app auth token gets refreshed. Parameter: Auth Token
Default:None
- get_user_auth_scope() List[twitchAPI.types.AuthScope] ¶
Returns the set User auth Scope
- refresh_used_token()¶
Refreshes the currently used token
- 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
- set_user_authentication(token: str, scope: List[twitchAPI.types.AuthScope], refresh_token: Optional[str] = None, validate: bool = True)¶
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 TrueDefault:None
validate (bool) – if true, validate the set token for being a user auth token and having the required scope
Default:True
- Raises
ValueError – if
auto_refresh_auth
is True but refresh_token is not setMissingScopeException – if given token is missing one of the required scopes
InvalidTokenException – if the given token is invalid or for a different client id
- get_app_token() Optional[str] ¶
Returns the app token that the api uses or None when not authenticated.
- get_user_auth_token() Optional[str] ¶
Returns the current user auth token, None if no user Authentication is set
- 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_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
- 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
- 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
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
- get_bits_leaderboard(count: Optional[int] = 10, period: Optional[twitchAPI.types.TimePeriod] = TimePeriod.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
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_extension_transactions(extension_id: str, transaction_id: Optional[Union[str, List[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 (union(list(str),str)) – Transaction IDs to look up. Can either be a list of str or str
Default:None
after (str) – cursor for forward pagination
Default:None
first (int) – Maximum number of objects returned, range 1 to 100,
Default:20
- 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
ValueError – if transaction_ids is longer than 100 entries
- 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
- 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
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
- 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
- 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
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_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
Default:None
- 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
- check_automod_status(broadcaster_id: str, automod_check_entries: List[twitchAPI.types.AutoModCheckEntry]) 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.
automod_check_entries (list[AutoModCheckEntry]) – The Automod Check Entries
- 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_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
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
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
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_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
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_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
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
- 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.CHANNEL_MANAGE_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
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
- 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
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_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
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
- 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
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
- check_user_subscription(broadcaster_id: str, user_id: str) dict ¶
Checks if a specific user (user_id) is subscribed to a specific channel (broadcaster_id).
Requires User or App Authorization with scope
twitchAPI.types.AuthScope.USER_READ_SUBSCRIPTIONS
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#check-user-subscription
- Parameters
- Return type
- Raises
UnauthorizedException – if app or user authentication is not set or invalid
MissingScopeException – if the app or 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
- 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
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_stream_tags(broadcaster_id: str) dict ¶
Gets the list of tags for a specified stream (channel).
Requires User 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