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.
- Returns
app token
- Return type
Union[str, None]
- 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_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
- get_chat_settings(broadcaster_id: str, moderator_id: Optional[str] = None)¶
Gets the broadcaster’s chat settings.
Requires App authentication
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-chat-settings
- Parameters
broadcaster_id (str) – The ID of the broadcaster whose chat settings you want to get.
moderator_id (str) – Required only to access the non_moderator_chat_delay or non_moderator_chat_delay_duration settings.
Default:None
- 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
- Return type
- update_chat_settings(broadcaster_id: str, moderator_id: str, emote_mode: Optional[bool] = None, follower_mode: Optional[bool] = None, follower_mode_duration: Optional[int] = None, non_moderator_chat_delay: Optional[bool] = None, non_moderator_chat_delay_duration: Optional[int] = None, slow_mode: Optional[bool] = None, slow_mode_wait_time: Optional[int] = None, subscriber_mode: Optional[bool] = None, unique_chat_mode: Optional[bool] = None)¶
Updates the broadcaster’s chat settings.
Requires User authentication with scope
twitchAPI.types.AuthScope.CHANNEL_MANAGE_CHAT_SETTINGS
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-chat-settings
- Parameters
broadcaster_id (str) – The ID of the broadcaster whose chat settings you want to update.
moderator_id (str) – The ID of a user that has permission to moderate the broadcaster’s chat room.
emote_mode (bool) – A Boolean value that determines whether chat messages must contain only emotes.
Default:None
follower_mode (bool) – A Boolean value that determines whether the broadcaster restricts the chat room to followers only, based on how long they’ve followed.
Default:None
follower_mode_duration (int) – The length of time, in minutes, that the followers must have followed the broadcaster to participate in the chat room
Default:None
non_moderator_chat_delay (bool) – A Boolean value that determines whether the broadcaster adds a short delay before chat messages appear in the chat room.
Default:None
non_moderator_chat_delay_duration (int) – he amount of time, in seconds, that messages are delayed from appearing in chat. Possible Values: 2, 4 and 6
Default:None
slow_mode (bool) – A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages.
Default:None
slow_mode_wait_time (int) – The amount of time, in seconds, that users need to wait between sending messages
Default:None
subscriber_mode (bool) – A Boolean value that determines whether only users that subscribe to the broadcaster’s channel can talk in the chat room.
Default:None
unique_chat_mode (bool) – A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room.
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 non_moderator_chat_delay_duration is not one of 2, 4 or 6
- 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.