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 True

    Default: 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 True

    Default: None

  • validate (bool) – if true, validate the set token for being a user auth token and having the required scope

    Default: True

Raises
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

dict

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

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

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

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

Parameters
  • after (str) – cursor for forward pagination

    Default: None

  • first (int) – Maximum number of objects returned, range 1 to 100,

    Default: 20

  • game_id (str) – Game ID

    Default: None

  • ended_at (datetime) – Ending date/time for returned reports, if this is provided, started_at must also be specified.

    Default: None

  • started_at (datetime) – Starting date/time for returned reports, if this is provided, ended_at must also be specified.

    Default: None

  • report_type (AnalyticsReportType) – Type of analytics report that is returned.

    Default: None

Raises
Return type

dict

get_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,

  • started_at (datetime) – Timestamp for the period over which the returned data is aggregated.

    Default: None

  • user_id (str) – ID of the user whose results are returned; i.e., the person who paid for the Bits.

    Default: None

Raises
Return type

dict

get_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
Return type

dict

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
Return type

dict

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
Return type

dict

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

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

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

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

Parameters
  • broadcaster_id (str) – Broadcaster ID of the stream from which the clip will be made.

  • has_delay (bool) – If False, the clip is captured from the live stream when the API is called; otherwise, a delay is added before the clip is captured (to account for the brief delay between the broadcaster’s stream and the viewer’s experience of that stream).

    Default: False

Raises
Return type

dict

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

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

Requires App or User authentication

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

Parameters
  • broadcaster_id (str) – ID of the broadcaster for whom clips are returned.

    Default: None

  • game_id (str) – ID of the game for which clips are returned.

    Default: None

  • clip_id (list[str]) – ID of the clip being queried. Limit: 100.

    Default: None

  • first (int) – Maximum number of objects to return. Maximum: 100.

    Default: 20

  • after (str) – Cursor for forward pagination

    Default: None

  • before (str) – Cursor for backward pagination

    Default: None

  • ended_at (datetime) – Ending date/time for returned clips

    Default: None

  • started_at (datetime) – Starting date/time for returned clips

    Default: None

Raises
Return type

dict

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

Gets the status of one or more provided Bits codes.

Requires App authentication

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

Parameters
  • code (list[str]) – The code to get the status of. Maximum of 20 entries

  • user_id (int) – Represents the numeric Twitch user ID of the account which is going to receive the entitlement associated with the code.

Raises
Return type

dict

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

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

Requires App authentication

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

Parameters
  • code (list[str]) – The code to redeem to the authenticated user’s account. Maximum of 20 entries

  • user_id (int) – Represents the numeric Twitch user ID of the account which is going to receive the entitlement associated with the code.

Raises
Return type

dict

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

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

Requires App or User authentication

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

Parameters
  • after (str) – Cursor for forward pagination

    Default: None

  • before (str) – Cursor for backward pagination

    Default: None

  • first (int) – Maximum number of objects to return. Maximum: 100.

    Default: 20

Raises
Return type

dict

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

Gets game information by game ID or name.

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

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

Parameters
  • game_ids (list[str]) – Game ID

    Default: None

  • names (list[str]) – Game Name

    Default: None

Raises
Return type

dict

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
Return type

dict

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

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

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

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

Parameters
  • broadcaster_id (str) – Provided broadcaster ID must match the user ID in the user auth token.

  • user_id (str) – Filters the results and only returns a status object for users who are banned in this channel and have a matching user_id

    Default: None

  • after (str) – Cursor for forward pagination

    Default: None

  • first (int) – Maximum number of objects to return. Maximum: 100.

    Default: 20

Raises
Return type

dict

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

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

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

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

Parameters
  • broadcaster_id (str) – Provided broadcaster ID must match the user ID in the user auth token.

  • user_id (str) – Filters the results and only returns a status object for users who are banned in this channel and have a matching user_id.

    Default: None

  • after (str) – Cursor for forward pagination

    Default: None

  • before (str) – Cursor for backward pagination

    Default: None

  • first (int) – Maximum number of objects to return. Maximum: 100.

    Default: 20

Raises
Return type

dict

ban_user(broadcaster_id: str, moderator_id: str, user_id: str, reason: str, duration: Optional[int] = None) dict

Bans a user from participating in a broadcaster’s chat room, or puts them in a timeout.

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

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

Parameters
  • broadcaster_id (str) – The ID of the broadcaster whose chat room the user is being banned from.

  • moderator_id (str) – The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token.

  • user_id (str) – The ID of the user to ban or put in a timeout.

  • reason (str) – The reason the user is being banned or put in a timeout. The text is user defined and limited to a maximum of 500 characters.

  • duration (int) – To ban a user indefinitely, don’t set this. Put a user in timeout for the number of seconds specified. Maximum 1_209_600 (2 weeks)

    Default: None

Raises
Return type

dict

unban_user(broadcaster_id: str, moderator_id: str, user_id: str) bool

Removes the ban or timeout that was placed on the specified user

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

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

Parameters
  • broadcaster_id (str) – The ID of the broadcaster whose chat room the user is banned from chatting in.

  • moderator_id (str) – The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token.

  • user_id (str) – The ID of the user to remove the ban or timeout from.

Raises
Return type

bool

get_blocked_terms(broadcaster_id: str, moderator_id: str, after: Optional[str] = None, first: Optional[int] = None) dict

Gets the broadcaster’s list of non-private, blocked words or phrases. These are the terms that the broadcaster or moderator added manually, or that were denied by AutoMod.

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

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

Parameters
  • broadcaster_id (str) – The ID of the broadcaster whose blocked terms you’re getting.

  • moderator_id (str) – The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token.

  • after (str) – The cursor used to get the next page of results.

    Default: None

  • first (int) – The maximum number of blocked terms to return per page in the response. Maximum 100

    Default: None

Raises
Return type

dict

add_blocked_term(broadcaster_id: str, moderator_id: str, text: str) dict

Adds a word or phrase to the broadcaster’s list of blocked terms. These are the terms that broadcasters don’t want used in their chat room.

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

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#add-blocked-term

Parameters
  • broadcaster_id (str) – The ID of the broadcaster that owns the list of blocked terms.

  • moderator_id (str) – The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token.

  • text (str) – The word or phrase to block from being used in the broadcaster’s chat room. Between 2 and 500 characters long

Raises
Return type

dict

remove_blocked_term(broadcaster_id: str, moderator_id: str, term_id: str) bool

Removes the word or phrase that the broadcaster is blocking users from using in their chat room.

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

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#remove-blocked-term

Parameters
  • broadcaster_id (str) – The ID of the broadcaster that owns the list of blocked terms.

  • moderator_id (str) – The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token.

  • term_id (str) – The ID of the blocked term you want to delete.

Raises
Return type

bool

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

Returns all moderators in a channel.

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

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

Parameters
  • broadcaster_id (str) – Provided broadcaster ID must match the user ID in the user auth token.

  • user_ids (list[str]) – Filters the results and only returns a status object for users who are moderator in this channel and have a matching user_id. Maximum 100

    Default: None

  • after (str) – Cursor for forward pagination

    Default: None

  • first (int) – Maximum number of objects to return. Maximum: 100.

    Default: 20

Raises
Return type

dict

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

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

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

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

Parameters
  • broadcaster_id (str) – Provided broadcaster ID must match the user ID in the user auth token.

  • user_ids (list[str]) – Filters the results and only returns a status object for users who are moderator in this channel and have a matching user_id. Maximum 100

    Default: None

  • after (str) – Cursor for forward pagination

    Default: None

  • first (int) – Maximum number of objects to return. Maximum: 100.

    Default: 20

Raises
Return type

dict

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
Return type

dict

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

Gets information about active streams. Streams are returned sorted by number of current viewers, in descending order. Across multiple pages of results, there may be duplicate or missing streams, as viewers join and leave streams.

Requires App or User authentication.

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

Parameters
  • after (str) – Cursor for forward pagination

    Default: None

  • before (str) – Cursor for backward pagination

    Default: None

  • first (int) – Maximum number of objects to return. Maximum: 100.

    Default: 20

  • game_id (list[str]) – Returns streams broadcasting a specified game ID. You can specify up to 100 IDs.

    Default: None

  • language (list[str]) – Stream language. You can specify up to 100 languages.

    Default: None

  • user_id (list[str]) – Returns streams broadcast by one or more specified user IDs. You can specify up to 100 IDs.

    Default: None

  • user_login (list[str]) – Returns streams broadcast by one or more specified user login names. You can specify up to 100 names.

    Default: None

Raises
Return type

dict

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

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

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

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

Only one of user_id and video_id must be specified.

Parameters
  • user_id (str) – ID of the broadcaster from whose stream markers are returned.

  • video_id (str) – ID of the VOD/video whose stream markers are returned.

  • after (str) – Cursor for forward pagination

    Default: None

  • before (str) – Cursor for backward pagination

    Default: None

  • first (int) – Number of values to be returned when getting videos by user or game ID. Limit: 100.

    Default: 20

Raises
Return type

dict

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

Get all of a broadcaster’s subscriptions.

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

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

Parameters
  • broadcaster_id (str) – User ID of the broadcaster. Must match the User ID in the Bearer token.

  • user_ids (list[str]) – Unique identifier of account to get subscription status of. Maximum 100 entries

    Default: None

  • after (str) – Cursor for forward pagination.

    Default: None

  • first (int) – Maximum number of objects to return. Maximum: 100.

    Default: 20

Raises
Return type

dict

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
  • broadcaster_id (str) – User ID of an Affiliate or Partner broadcaster.

  • user_id (str) – User ID of a Twitch viewer.

Return type

dict

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

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

Requires App authentication

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

Parameters
  • after (str) – Cursor for forward pagination

    Default: None

  • first (int) – Maximum number of objects to return. Maximum: 100.

    Default: 20

  • tag_ids (list[str]) – IDs of tags. Maximum 100 entries

    Default: None

Raises
Return type

dict

get_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
Return type

dict

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

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

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

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

Parameters
  • broadcaster_id (str) – ID of the stream for which tags are to be replaced.

  • tag_ids (list[str]) – IDs of tags to be applied to the stream. Maximum of 100 supported.

Returns

{}

Raises
Return type

dict

get_channel_teams(broadcaster_id: str) dict

Retrieves a list of Twitch Teams of which the specified channel/broadcaster is a member.

Requires User or App authentication.

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

Parameters

broadcaster_id (str) – User ID for a Twitch user.

Return type

dict

Raises
get_teams(team_id: Optional[str] = None, name: Optional[str] = None) dict

Gets information for a specific Twitch Team.

Requires User or App authentication. One of the two optional query parameters must be specified.

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

Parameters
  • team_id (str) – Team ID

    Default: None

  • name (str) – Team Name

    Default: None

Raises
Return type

dict

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

Gets information about one or more specified Twitch users. Users are identified by optional user IDs and/or login name. If neither a user ID nor a login name is specified, the user is the one authenticated.

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

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

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

Parameters
  • user_ids (list[str]) – User ID. Multiple user IDs can be specified. Limit: 100.

    Default: None

  • logins (list[str]) – User login name. Multiple login names can be specified. Limit: 100.

    Default: None

Raises
Return type

dict

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

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

Requires App authentication.

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

Parameters
  • after (str) – Cursor for forward pagination

    Default: None

  • first (int) – Maximum number of objects to return. Maximum: 100.

    Default: 20

  • from_id (str) – User ID. The request returns information about users who are being followed by the from_id user.

    Default: None

  • to_id (str) – User ID. The request returns information about users who are following the to_id user.

    Default: None

Raises
Return type

dict

update_user(description: str) dict

Updates the description of the Authenticated user.

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

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

Parameters

description (str) – User’s account description

Raises
Return type

dict

get_user_extensions() dict

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

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

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

Raises
Return type

dict

get_user_active_extensions(user_id: Optional[str] = None) dict

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

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

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

Parameters

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

Default: None

Raises
Return type

dict

update_user_extensions(data: dict) dict

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

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

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

Parameters

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

Raises
Return type

dict

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, sort: twitchAPI.types.SortMethod = SortMethod.TIME, video_type: twitchAPI.types.VideoType = VideoType.ALL) dict

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

Requires App authentication.

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

Parameters
  • ids (list[str]) – ID of the video being queried. Limit: 100.

    Default: None

  • user_id (str) – ID of the user who owns the video.

    Default: None

  • game_id (str) – ID of the game the video is of.

    Default: None

  • after (str) – Cursor for forward pagination

    Default: None

  • before (str) – Cursor for backward pagination

    Default: None

  • first (int) – Number of values to be returned when getting videos by user or game ID. Limit: 100.

    Default: 20

  • language (str) – Language of the video being queried.

    Default: None

  • period (TimePeriod) – Period during which the video was created.

    Default: TimePeriod.ALL

  • sort (SortMethod) – Sort order of the videos.

    Default: SortMethod.TIME

  • video_type (VideoType) – Type of video.

    Default: VideoType.ALL

Raises
Return type

dict

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

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

Requires App authentication

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

Parameters
  • first (int) – Number of values to be returned per page. Limit: 100.

    Default: 20

  • after (str) – Cursor for forward pagination

    Default: None

Raises
Return type

dict

get_channel_information(broadcaster_id: Union[str, List[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 (union[str,list[str]]) – ID of the channel to be updated, can either be a string or a list of strings with up to 100 entries

Raises
Return type

dict

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

Modifies channel information for users.

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

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

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

  • game_id (str) – The current game ID being played on the channel

    Default: None

  • broadcaster_language (str) – The language of the channel

    Default: None

  • title (str) – The title of the stream

    Default: None

  • delay (int) – Stream delay in seconds. Trying to set this while not being a Twitch Partner will fail!

    Default: None

Raises
Return type

bool

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

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

Requires App authentication

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

Parameters
  • query (str) – search query

  • first (int) – Maximum number of objects to return. Maximum: 100

    Default: 20

  • after (str) – Cursor for forward pagination

    Default: None

  • live_only (bool) – Filter results for live streams only.

    Default: False

Raises
Return type

dict

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

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

Requires App authentication

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

Parameters
  • query (str) – search query

  • first (int) – Maximum number of objects to return. Maximum: 100

    Default: 20

  • after (str) – Cursor for forward pagination

    Default: None

Raises
Return type

dict

get_stream_key(broadcaster_id: str) dict

Gets the channel stream key for a user.

Requires User authentication with twitchAPI.types.AuthScope.CHANNEL_READ_STREAM_KEY

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

Parameters

broadcaster_id (str) – User ID of the broadcaster

Raises
Return type

dict

start_commercial(broadcaster_id: str, length: int) dict

Starts a commercial on a specified channel.

Requires User authentication with twitchAPI.types.AuthScope.CHANNEL_EDIT_COMMERCIAL

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

Parameters
  • broadcaster_id (str) – ID of the channel requesting a commercial

  • length (int) – Desired length of the commercial in seconds. , one of these: [30, 60, 90, 120, 150, 180]

Raises
Return type

dict

get_cheermotes(broadcaster_id: str) dict

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

Requires App authentication

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

Parameters

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

Raises
Return type

dict

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

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

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

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

Parameters
  • broadcaster_id (str) – User ID of the broadcaster.

  • first (int) – Maximum number of objects to return. Maximum: 100.

    Default: 1

  • id (str) – The id of the wanted event, if known

    Default: None

  • cursor (str) – Cursor for forward pagination

    Default: None

Raises
Return type

dict

get_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 or User authentication

See Twitch documentation for valid parameter combinations!

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

Parameters
  • id (str) – Unique Identifier of the entitlement

    Default: None

  • user_id (str) – A Twitch User ID

    Default: None

  • game_id (str) – A Twitch Game ID

    Default: None

  • after (str) – The cursor used to fetch the next page of data.

    Default: None

  • first (int) – Maximum number of entitlements to return. Maximum: 100

    Default: 20

Raises
Return type

dict

create_custom_reward(broadcaster_id: str, title: str, cost: int, prompt: Optional[str] = None, 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

  • cost (int) – The cost of the reward

  • prompt (str) – The prompt for the viewer when they are redeeming the reward

    Default: None

  • is_enabled – Is the reward currently enabled, if false the reward won’t show up to viewers.

    Default: True

  • background_color (str) – Custom background color for the reward. Format: Hex with # prefix. Example: #00E5CB.

    Default: None

  • is_user_input_required (bool) – Does the user need to enter information when redeeming the reward.

    Default: False

  • is_max_per_stream_enabled (bool) – Whether a maximum per stream is enabled.

    Default: False

  • max_per_stream (int) – The maximum number per stream if enabled

    Default: None

  • is_max_per_user_per_stream_enabled (bool) – Whether a maximum per user per stream is enabled.

    Default: False

  • max_per_user_per_stream (int) – The maximum number per user per stream if enabled

    Default: None

  • is_global_cooldown_enabled (bool) – Whether a cooldown is enabled.

    Default: False

  • global_cooldown_seconds (int) – The cooldown in seconds if enabled

    Default: None

  • should_redemptions_skip_request_queue (bool) – Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status.

    Default: False

Raises
Return type

dict

delete_custom_reward(broadcaster_id: str, reward_id: str)

Deletes a Custom Reward on a channel.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_REDEMPTIONS

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

Parameters
  • broadcaster_id (str) – Provided broadcaster_id must match the user_id in the auth token

  • reward_id (str) – ID of the Custom Reward to delete, must match a Custom Reward on broadcaster_id’s channel.

Raises
get_custom_reward(broadcaster_id: str, reward_id: Optional[Union[str, 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 (union[list[str],str]) – When used, this parameter filters the results and only returns reward objects for the Custom Rewards with matching ID. Maximum: 50 Can be either a list of str or str

    Default: None

  • only_manageable_rewards (bool) – When set to true, only returns custom rewards that the calling client_id can manage.

    Default: false

Return type

dict

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

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

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_READ_REDEMPTIONS

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

Parameters
  • broadcaster_id (str) – Provided broadcaster_id must match the user_id in the auth token

  • reward_id (str) – When ID is not provided, this parameter returns paginated Custom Reward Redemption objects for redemptions of the Custom Reward with ID reward_id

  • id (list(str)) – When used, this param filters the results and only returns

    Default: None Custom Reward Redemption objects for the redemptions with matching ID. Maximum: 50 ids
    Default: None

  • status (CustomRewardRedemptionStatus) – When id is not provided, this param is required and filters the paginated Custom Reward Redemption objects for redemptions with the matching status.

    Default: None

  • sort (SortOrder) – Sort order of redemptions returned when getting the paginated Custom Reward Redemption objects for a reward.

    Default: SortOrder.OLDEST

  • after (str) – Cursor for forward pagination.

    Default: None

  • first (int) – Number of results to be returned when getting the paginated Custom Reward Redemption objects for a reward. Limit: 50

    Default: 20

Return type

dict

Raises
update_custom_reward(broadcaster_id: str, reward_id: str, title: Optional[str] = None, prompt: Optional[str] = None, cost: Optional[int] = None, 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

    Default: None

  • prompt (str) – The prompt for the viewer when they are redeeming the reward

    Default: None

  • cost (int) – The cost of the reward

    Default: None

  • is_enabled – Is the reward currently enabled, if false the reward won’t show up to viewers.

    Default: true

  • background_color (str) – Custom background color for the reward.

    Default: None Format: Hex with # prefix. Example: #00E5CB.

  • is_user_input_required (bool) – Does the user need to enter information when redeeming the reward.

    Default: false

  • is_max_per_stream_enabled (bool) – Whether a maximum per stream is enabled.

    Default: false

  • max_per_stream (int) – The maximum number per stream if enabled

    Default: None

  • is_max_per_user_per_stream_enabled (bool) – Whether a maximum per user per stream is enabled.

    Default: false

  • max_per_user_per_stream (int) – The maximum number per user per stream if enabled

    Default: None

  • is_global_cooldown_enabled (bool) – Whether a cooldown is enabled.

    Default: false

  • global_cooldown_seconds (int) – The cooldown in seconds if enabled

    Default: None

  • should_redemptions_skip_request_queue (bool) – Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status.

    Default: false

Raises
  • TwitchAPIException – if the request was malformed

  • ValueError – if is_global_cooldown_enabled is True but global_cooldown_seconds is not specified

  • ValueError – if is_max_per_stream_enabled is True but max_per_stream is not specified

  • ValueError – if is_max_per_user_per_stream_enabled is True but max_per_user_per_stream is not specified

  • UnauthorizedException – if user authentication is not set or invalid

  • MissingScopeException – if the user authentication is missing the required scope

  • TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed

  • TwitchBackendException – if the Twitch API itself runs into problems

  • TwitchAPIException – if a Query Parameter is missing or invalid

  • TwitchAPIException – if Channel Points are not available for the broadcaster or the custom reward belongs to a different broadcaster

  • ValueError – if the given reward_id does not match a custom reward by the given broadcaster

Return type

dict

update_redemption_status(broadcaster_id: str, reward_id: str, redemption_ids: Union[List[str], 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 (union(list(str),str)) – IDs of the Custom Reward Redemption to update, must match a Custom Reward Redemption on broadcaster_id’s channel Max: 50 Can either be a list of str or str

  • status (CustomRewardRedemptionStatus) – The new status to set redemptions to.

Raises
Return type

dict

get_channel_editors(broadcaster_id: str) dict

Gets a list of users who have editor permissions for a specific channel.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_READ_EDITORS

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

Parameters

broadcaster_id (str) – Broadcaster’s user ID associated with the channel

Raises
Return type

dict

delete_videos(video_ids: List[str]) Union[bool, dict]

Deletes one or more videos. Videos are past broadcasts, Highlights, or uploads. Returns False if the User was not Authorized to delete at least one of the given videos.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_VIDEOS

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

Parameters

video_ids (list(str)) – ids of the videos, Limit: 5 ids

Raises
Return type

dict or False

get_user_block_list(broadcaster_id: str, first: Optional[int] = 20, after: Optional[str] = None) dict

Gets a specified user’s block list. The list is sorted by when the block occurred in descending order (i.e. most recent block first).

Requires User Authentication with twitchAPI.types.AuthScope.USER_READ_BLOCKED_USERS

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

Parameters
  • broadcaster_id (str) – User ID for a twitch user

  • first (int) – Maximum number of objects to return. Maximum: 100.

    Default: 20

  • after (str) – Cursor for forward pagination

    Default: None

Raises
Return type

dict

block_user(target_user_id: str, source_context: Optional[twitchAPI.types.BlockSourceContext] = None, reason: Optional[twitchAPI.types.BlockReason] = None) bool

Blocks the specified user on behalf of the authenticated user.

Requires User Authentication with twitchAPI.types.AuthScope.USER_MANAGE_BLOCKED_USERS

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

Parameters
  • target_user_id (str) – User ID of the user to be blocked.

  • source_context (BlockSourceContext) – Source context for blocking the user. Optional

    Default: None

  • reason (BlockReason) – Reason for blocking the user. Optional.

    Default: None

Raises
Return type

bool

unblock_user(target_user_id: str) bool

Unblocks the specified user on behalf of the authenticated user.

Requires User Authentication with twitchAPI.types.AuthScope.USER_MANAGE_BLOCKED_USERS

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

Parameters

target_user_id (str) – User ID of the user to be unblocked.

Raises
Return type

bool

get_followed_streams(user_id: str, after: Optional[str] = None, first: Optional[int] = 100) dict

Gets information about active streams belonging to channels that the authenticated user follows. 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 User Authentication with twitchAPI.types.AuthScope.USER_READ_FOLLOWS

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

Parameters
  • user_id (str) – Results will only include active streams from the channels that this Twitch user follows. user_id must match the User ID in the bearer token.

  • after (str) – Cursor for forward pagination.

    Default: None

  • first (int) – Maximum number of objects to return. Maximum 100

    Default: 100

Raises
Return type

dict

get_polls(broadcaster_id: str, poll_id: Optional[str] = None, after: Optional[str] = None, first: Optional[int] = 20) dict

Get information about all polls or specific polls for a Twitch channel. Poll information is available for 90 days.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_READ_POLLS

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

Parameters
  • broadcaster_id (str) – The broadcaster running polls. Provided broadcaster_id must match the user_id in the user OAuth token.

  • poll_id (str) – ID of a poll.

    Default: None

  • after (str) – Cursor for forward pagination.

    Default: None

  • first (int) – Maximum number of objects to return. Maximum 20

    Default: 20

Raises
Return type

dict

create_poll(broadcaster_id: str, title: str, choices: List[str], duration: int, bits_voting_enabled: bool = False, bits_per_vote: Optional[int] = None, channel_points_voting_enabled: bool = False, channel_points_per_vote: Optional[int] = None) dict

Create a poll for a specific Twitch channel.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_POLLS

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

Parameters
  • broadcaster_id (str) – The broadcaster running the poll

  • title (str) – Question displayed for the poll

  • choices (List[str]) – List of poll choices.

  • duration (int) – Total duration for the poll (in seconds). Minimum 15, Maximum 1800

  • bits_voting_enabled (bool) – Indicates if Bits can be used for voting.

    Default: False

  • bits_per_vote (int) – Number of Bits required to vote once with Bits. Minimum: 0. Maximum: 10000.

    Default: None

  • channel_points_voting_enabled (bool) – Indicates if Channel Points can be used for voting.

    Default: False

  • channel_points_per_vote (int) – Number of Channel Points required to vote once with Channel Points. Minimum: 0. Maximum: 1000000.

    Default: None

Raises
Return type

dict

end_poll(broadcaster_id: str, poll_id: str, status: twitchAPI.types.PollStatus) dict

End a poll that is currently active.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_POLLS

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

Parameters
  • broadcaster_id (str) – id of the broadcaster running the poll

  • poll_id (str) – id of the poll

  • status (PollStatus) – The poll status to be set

Raises
Return type

dict

get_predictions(broadcaster_id: str, prediction_ids: Optional[List[str]] = None, after: Optional[str] = None, first: Optional[int] = 20) dict

Get information about all Channel Points Predictions or specific Channel Points Predictions for a Twitch channel. Results are ordered by most recent, so it can be assumed that the currently active or locked Prediction will be the first item.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_READ_PREDICTIONS

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

Parameters
  • broadcaster_id (str) – The broadcaster running the prediction

  • prediction_ids (List[str]) – List of prediction ids.

    Default: None

  • after (str) – Cursor for forward pagination.

    Default: None

  • first (int) – Maximum number of objects to return. Maximum 20

    Default: 20

Raises
Return type

dict

create_prediction(broadcaster_id: str, title: str, outcomes: List[str], prediction_window: int) dict

Create a Channel Points Prediction for a specific Twitch channel.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_PREDICTIONS

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

Parameters
  • broadcaster_id (str) – The broadcaster running the prediction

  • title (str) – Title of the Prediction

  • outcomes (list[str]) – List of possible Outcomes, must contain exactly 2 entries

  • prediction_window (int) – Total duration for the Prediction (in seconds). Minimum 1, Maximum 1800

Raises
Return type

dict

end_prediction(broadcaster_id: str, prediction_id: str, status: twitchAPI.types.PredictionStatus, winning_outcome_id: Optional[str] = None)

Lock, resolve, or cancel a Channel Points Prediction.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_PREDICTIONS

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

Parameters
  • broadcaster_id (str) – ID of the broadcaster

  • prediction_id (str) – ID of the Prediction

  • status (PredictionStatus) – The Prediction status to be set.

  • winning_outcome_id (str) – ID of the winning outcome for the Prediction.

    Default: None

Raises
Return type

dict

manage_held_automod_message(user_id: str, msg_id: str, action: twitchAPI.types.AutoModAction) bool

Allow or deny a message that was held for review by AutoMod.

Requires User Authentication with twitchAPI.types.AuthScope.MODERATOR_MANAGE_AUTOMOD

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#manage-held-automod-messages

Parameters
  • user_id (str) – The moderator who is approving or rejecting the held message.

  • msg_id (str) – ID of the targeted message

  • action (AutoModAction) – The action to take for the message.

Raises
Return type

dict

get_chat_badges(broadcaster_id: str) dict

Gets a list of custom chat badges that can be used in chat for the specified channel.

Requires User or App Authentication

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

Parameters

broadcaster_id

Raises
Return type

dict

get_global_chat_badges() dict

Gets a list of chat badges that can be used in chat for any channel.

Requires User or App Authentication

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

Raises
Return type

dict

get_channel_emotes(broadcaster_id: str) dict

Gets all emotes that the specified Twitch channel created.

Requires User or App Authentication

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

Parameters

broadcaster_id (str) – ID of the broadcaster

Raises
Return type

dict

get_global_emotes() dict

Gets all global emotes.

Requires User or App Authentication

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

Raises
Return type

dict

get_emote_sets(emote_set_id: List[str]) dict

Gets emotes for one or more specified emote sets.

Requires User or App Authentication

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

Parameters

emote_set_id (list[str]) – A list of IDs that identify the emote sets.

Raises
Return type

dict

delete_eventsub_subscription(subscription_id: str) bool

Deletes an EventSub subscription.

Requires App Authentication

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

Parameters

subscription_id (str) – The ID of the subscription

Raises
Return type

bool

get_eventsub_subscriptions(status: Optional[str] = None, sub_type: Optional[str] = None, after: Optional[str] = None)

Gets a list of your EventSub subscriptions. The list is paginated and ordered by the oldest subscription first.

Requires App Authentication

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

Parameters
  • status (str) – Filter subscriptions by its status.

    Default: None

  • sub_type (str) – Filter subscriptions by subscription type.

    Default: None

  • after (str) – The cursor used to get the next page of results.

    Default: None

Raises
Return type

dict

get_channel_stream_schedule(broadcaster_id: str, stream_segment_ids: Optional[List[str]] = None, start_time: Optional[datetime.datetime] = None, utc_offset: Optional[str] = None, first: Optional[int] = 20, after: Optional[str] = None) dict

Gets all scheduled broadcasts or specific scheduled broadcasts from a channel’s stream schedule.

Requires App or User Authentication

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

Parameters
  • broadcaster_id (str) – user id of the broadcaster

  • stream_segment_ids (list[str]) – optional list of stream segment ids. Maximum 100 entries.

    Default: None

  • start_time (datetime) – optional timestamp to start returning stream segments from.

    Default: None

  • utc_offset (str) – A timezone offset to be used.

    Default: None

  • first (int) – Maximum Number of stream segments to return. Maximum 25.

    Default: 20

  • after (str) – Cursor for forward pagination

    Default: None

Raises
Return type

dict

get_channel_icalendar(broadcaster_id: str) str

Gets all scheduled broadcasts from a channel’s stream schedule as an iCalendar.

Does not require Authorization

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

Parameters

broadcaster_id (str) – id of the broadcaster

Raises
Return type

str

update_channel_stream_schedule(broadcaster_id: str, is_vacation_enabled: Optional[bool] = None, vacation_start_time: Optional[datetime.datetime] = None, vacation_end_time: Optional[datetime.datetime] = None, timezone: Optional[str] = None) bool

Update the settings for a channel’s stream schedule. This can be used for setting vacation details.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_SCHEDULE

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

Parameters
  • broadcaster_id (str) – id of the broadcaster

  • is_vacation_enabled (bool) – indicates if Vacation Mode is enabled.

    Default: None

  • vacation_start_time (datetime) – Start time for vacation

    Default: None

  • vacation_end_time (datetime) – End time for vacation specified

    Default: None

  • timezone (str) – The timezone for when the vacation is being scheduled using the IANA time zone database format.

Raises
Return type

bool

create_channel_stream_schedule_segment(broadcaster_id: str, start_time: datetime.datetime, timezone: str, is_recurring: bool, duration: Optional[str] = None, category_id: Optional[str] = None, title: Optional[str] = None) dict

Create a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_SCHEDULE

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

Parameters
  • broadcaster_id (str) – id of the broadcaster

  • start_time (datetime) – Start time for the scheduled broadcast

  • timezone (str) – The timezone of the application creating the scheduled broadcast using the IANA time zone database format.

  • is_recurring (bool) – Indicates if the scheduled broadcast is recurring weekly.

  • duration (str) – Duration of the scheduled broadcast in minutes from the start_time.

    Default: 240

  • category_id (str) – Game/Category ID for the scheduled broadcast.

    Default: None

  • title (str) – Title for the scheduled broadcast.

    Default: None

Raises
Return type

dict

update_channel_stream_schedule_segment(broadcaster_id: str, stream_segment_id: str, start_time: Optional[datetime.datetime] = None, duration: Optional[str] = None, category_id: Optional[str] = None, title: Optional[str] = None, is_canceled: Optional[bool] = None, timezone: Optional[str] = None) dict

Update a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_SCHEDULE

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-channel-stream-schedule-segment

Parameters
  • broadcaster_id (str) – id of the broadcaster

  • stream_segment_id (str) – The ID of the streaming segment to update.

  • start_time (datetime) – Start time for the scheduled broadcast

    Default: None

  • duration (str) – Duration of the scheduled broadcast in minutes from the start_time.

    Default: 240

  • category_id (str) – Game/Category ID for the scheduled broadcast.

    Default: None

  • title (str) – Title for the scheduled broadcast.

    Default: None

  • is_canceled (bool) – Indicated if the scheduled broadcast is canceled.

    Default: None

  • timezone (str) – The timezone of the application creating the scheduled broadcast using the IANA time zone database format.

    Default: None

Raises
Return type

dict

delete_channel_stream_schedule_segment(broadcaster_id: str, stream_segment_id: str) bool

Delete a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule.

Requires User Authentication with twitchAPI.types.AuthScope.CHANNEL_MANAGE_SCHEDULE

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#delete-channel-stream-schedule-segment

Parameters
  • broadcaster_id (str) – id of the broadcaster

  • stream_segment_id (str) – The ID of the streaming segment to delete.

Raises
Return type

bool

update_drops_entitlements(entitlement_ids: List[str], fulfillment_status: twitchAPI.types.EntitlementFulfillmentStatus) dict

Updates the fulfillment status on a set of Drops entitlements, specified by their entitlement IDs.

Requires User or App Authentication

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

Parameters
Raises
Return type

dict