twitchAPI.twitch

The Twitch API client

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

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

Example Usage:

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

Authentication

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

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

App Authentication

App authentication is super simple, just do the following:

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

User Authentication

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

See twitchAPI.oauth for more info.

Class Documentation:

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

Twitch API client

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

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

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

Authenticate with a fresh generated app token

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

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

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

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

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

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

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

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

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

Parameters:
  • broadcaster_id (str) – Broadcaster ID of the stream from which the clip will be made.
  • has_delay (bool) – If False, the clip is captured from the live stream when the API is called; otherwise, a delay is added before the clip is captured (to account for the brief delay between the broadcaster’s stream and the viewer’s experience of that stream).
    Default: False
Raises:
Return type:

dict
create_entitlement_grants_upload_url(manifest_id: str) → dict

Creates a URL where you can upload a manifest file and notify users that they have an entitlement. Entitlements are digital items that users are entitled to use. Twitch entitlements are granted to users gratis or as part of a purchase on Twitch.

Requires App authentication

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

Parameters:

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

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

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

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

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

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

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

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

Requires User authentication with twitchAPI.types.AuthScope.USER_EDIT_FOLLOWS

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

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

bool
delete_user_follows(from_id: str, to_id: str) → bool

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

Requires User authentication with twitchAPI.types.AuthScope.USER_EDIT_FOLLOWS

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

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

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

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

Requires App authentication

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

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

dict
get_app_token() → Optional[str]

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

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

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

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

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

Parameters:
  • broadcaster_id (str) – Provided broadcaster ID must match the user ID in the user auth token.
  • user_id (str) – Filters the results and only returns a status object for users who are banned in this channel and have a matching user_id
  • after (str) – Cursor for forward pagination
  • 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, 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.
  • after (str) – Cursor for forward pagination
  • before (str) – Cursor for backward pagination
Raises:
Return type:

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

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

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

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

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

dict
get_broadcaster_subscriptions(broadcaster_id: str, user_ids: Optional[List[str]] = None) → 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
Raises:
Return type:

dict
get_channel_information(broadcaster_id: str) → dict

Gets channel information for users.

Requires App or user authentication

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

Parameters:

broadcaster_id (str) – ID of the channel to be updated
Raises:
Return type:

dict
get_cheermotes(broadcaster_id: str) → dict

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

Requires App authentication

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

Parameters:

broadcaster_id (str) – ID for the broadcaster who might own specialized Cheermotes.
Raises:
Return type:

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

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

Requires App or User authentication

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

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

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

Gets the status of one or more provided Bits codes.

Requires App authentication

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

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

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

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

OAuth Token Client ID must have ownership of Game

Requires App authentication

See Twitch documentation for valid parameter combinations!

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

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

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

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

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

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

Parameters:
  • after (str) – cursor for forward pagination
  • extension_id (str) – If this is specified, the returned URL points to an analytics report for just the specified extension.
  • 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.
  • started_at (datetime) – Starting date/time for returned reports, if this is provided, ended_at must also be specified.
  • report_type (AnalyticsReportType) – Type of analytics report that is returned
Return type:

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

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

Requires App authentication

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

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

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

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

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

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

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

dict
get_moderator_events(broadcaster_id: str, user_ids: Optional[List[str]] = None) → 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
Raises:
Return type:

dict
get_moderators(broadcaster_id: str, user_ids: Optional[List[str]] = None, 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
  • after (str) – Cursor for forward pagination
Raises:
Return type:

dict
get_stream_key(broadcaster_id: str) → dict

Gets the channel stream key for a user.

Requires User authentication with twitchAPI.types.AuthScope.CHANNEL_READ_STREAM_KEY

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

Parameters:

broadcaster_id (str) – User ID of the broadcaster
Raises:
Return type:

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

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

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

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

Only one of user_id and video_id must be specified.

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

dict
get_stream_tags(broadcaster_id: str) → dict

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

Requires App authentication

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

Parameters:

broadcaster_id (str) – ID of the stream thats tags are going to be fetched
Raises:
Return type:

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

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

Requires App or User authentication.

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

Parameters:
  • after (str) – Cursor for forward pagination
  • before (str) – Cursor for backward pagination
  • 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.
  • language (list[str]) – Stream language. You can specify up to 100 languages.
  • user_id (list[str]) – Returns streams broadcast by one or more specified user IDs. You can specify up to 100 IDs.
  • user_login (list[str]) – Returns streams broadcast by one or more specified user login names. You can specify up to 100 names.
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
  • before (str) – Cursor for backward pagination
  • first (int) – Maximum number of objects to return. Maximum: 100.
    Default: 20
Raises:
Return type:

dict
get_used_token() → Optional[str]

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

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

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

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

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

Parameters:

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

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

Returns the set User auth Scope

get_user_auth_token() → Optional[str]

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

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

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

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

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

Raises:
Return type:

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

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

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

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

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

Parameters:
  • user_ids (list[str]) – User ID. Multiple user IDs can be specified. Limit: 100.
  • logins (list[str]) – User login name. Multiple login names can be specified. Limit: 100.
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
  • 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.
  • to_id (str) – User ID. The request returns information about users who are following the to_id user.
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: int = 20, language: Optional[str] = None, period: twitchAPI.types.TimePeriod = <TimePeriod.ALL: 'all'>, sort: twitchAPI.types.SortMethod = <SortMethod.TIME: 'time'>, video_type: twitchAPI.types.VideoType = <VideoType.ALL: 'all'>) → dict

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

Requires App authentication.

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

Parameters:
  • ids (list[str]) – ID of the video being queried. Limit: 100.
  • user_id (str) – ID of the user who owns the video.
  • game_id (str) – ID of the game the video is of.
  • after (str) – Cursor for forward pagination
  • before (str) – Cursor for backward pagination
  • 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.
  • period (TimePeriod) – Period during which the video was created.
  • sort (SortMethod) – Sort order of the videos.
  • video_type (VideoType) – Type of video.
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
Raises:
Return type:

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

Modifies channel information for users.

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

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

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

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

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

Requires App authentication

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

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

dict
refresh_used_token()

Refreshes the currently used token

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

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

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

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

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

{}
Raises:
Return type:

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

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

Requires App authentication

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

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

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

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

Requires App authentication

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

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

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

Set a user token to be used.

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

None
Raises:

ValueError – if auto_refresh_auth is True but refresh_token is not set
start_commercial(broadcaster_id: str, length: int) → dict

Starts a commercial on a specified channel.

Requires User authentication with twitchAPI.types.AuthScope.CHANNEL_EDIT_COMMERCIAL

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

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

dict
update_user(description: str) → dict

Updates the description of the Authenticated user.

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

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

Parameters:

description (str) – User’s account description
Raises:
Return type:

dict
update_user_extensions(data: dict) → dict

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

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

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

Parameters:

data (dict) – The user extension data to be written
Raises:
Return type:

dict