Classes

`AppAPI` ¶

Bases: BaseAPI

`add_suspicious_user_status(target_user_id, moderator_id, broadcaster_id, status)` `async` ¶

Adds a suspicious user status to a chatter on the broadcaster's channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	moderator:manage:suspicious_users	None
User Access	moderator:manage:suspicious_users	Token holder is moderator

Parameters:

Name	Type	Description	Default
`target_user_id`	`str`	The ID of the user being given the suspicious status.	required
`moderator_id`	`str`	The user ID of the moderator who is applying the status.	required
`status`	`Literal['ACTIVE_MONITORING', 'RESTRICTED']`	The type of suspicious status. Possible values are: ACTIVE_MONITORING, RESTRICTED	required
`broadcaster_id`	`str`	The ID of the broadcaster. Defaults to the current user.	required

Returns:

Type	Description
`SuspiciousUserStatus`	The suspicious user status that was applied.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid. If the status specified was invalid. If the status update is not allowed for this user.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`create_clip_from_vod(broadcaster_id, vod_id, vod_offset, title, editor_id=None, duration=None)` `async` ¶

Creates a clip from a broadcaster's VOD on behalf of the broadcaster or an editor of the channel. Since a live stream is actively creating a VOD, this endpoint can also be used to create a clip from earlier in the current stream.

The duration of a clip can be from 5 seconds to 60 seconds in length, with a default of 30 seconds if not specified.

vod_offset indicates where the clip will end. In other words, the clip will start at (vod_offset - duration) and end at vod_offset. This means that the value of vod_offset must be greater than or equal to the value of duration.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	editor:manage:clips or channel:manage:clips	None
User Access	editor:manage:clips or channel:manage:clips	Token holder is editor or broadcaster

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`str`	The user ID for the channel you want to create a clip for.	required
`vod_id`	`str`	ID of the VOD the user wants to clip.	required
`vod_offset`	`int`	Offset in the VOD to create the clip. See notes above.	required
`title`	`str`	The title of the clip.	required
`editor_id`	`Optional[str]`	The user ID of the editor for the channel you want to create a clip for. If using the broadcaster's auth token, this is the same as broadcaster_id. This must match the user_id in the user access token. If None, uses broadcaster_id.	`None`
`duration`	`Optional[float]`	The length of the clip, in seconds. Precision is 0.1. Defaults to 30. Min: 5 seconds, Max: 60 seconds.	`None`

Returns:

Type	Description
`CreatedClip`	The created clip with edit URL.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token with required scope.
`BadRequest`	If invalid source type, missing required fields, broadcaster_id is required but not provided, broadcaster not found, category is not clippable, title did not pass AutoMod checks, or broadcaster is banned.
`Unauthorized`	If the Authorization header is required and must specify user access token, the user access token must include the editor:manage:clips or channel:manage:clips scope, the OAuth token is not valid, or the ID in the Client-Id header must match the Client ID in the OAuth token.
`Forbidden`	If the broadcaster has restricted the ability to capture clips to followers and/or subscribers only, the specified broadcaster has not enabled clips on their channel, the user defined by the editor_id is not authorized to create Clips, or the user is banned or timed out from the broadcaster's channel.
`NotFound`	If the broadcaster in the broadcaster_id query parameter must be broadcasting live, the VOD is not found, or the broadcaster_id or the editor_id does not exist.

`create_conduit(shard_count)` `async` ¶

Creates a conduit for EventSub.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None

Parameters:

Name	Type	Description	Default
`shard_count`	`int`	The number of shards to create. Max 20000.	required

Returns:

Type	Description
`Conduit`	The created Conduit.

Raises:

Type	Description
`ValueError`	If shard_count > 20000.
`TokenError`	If missing a valid app access token.
`BadRequest`	If shard_count is invalid.
`Unauthorized`	If the token is invalid or expired.
`RateLimited`	reached the maximum conduits allowed.

`create_eventsub_subscription(subscription_type, subscription_version, transport, condition)` `async` ¶

Creates an EventSub subscription to receive notifications when events occur.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	Varies by type	For webhook/conduit
User Access	Varies by type	For websocket

Parameters:

Name	Type	Description	Default
`subscription_type`	`str`	The type of subscription to create. For a list of subscription types, see Subscription Types in the Twitch API documentation.	required
`subscription_version`	`str`	The version number that identifies the definition of the subscription's data.	required
`transport`	`Dict[str, Any]`	The transport details used to send the notifications. Must contain 'method' (either 'webhook' or 'websocket') and additional fields based on the method: - For webhook: 'callback' (URL) and optionally 'secret' - For websocket: 'session_id'	required
`condition`	`Dict[str, Any]`	The subscription's parameter values. Contents are determined by the subscription type.	required

Returns:

Type	Description
`Tuple[Subscription, Tuple[int, int, int]]`	A tuple containing: - The created Subscription object - A tuple of (total_subscriptions, total_cost, max_total_cost)

Raises:

Type	Description
`TokenError`	If using webhooks/conduits without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the request parameters are invalid or the subscription type/version is not supported.
`Unauthorized`	If the token is invalid or expired.
`Conflict`	If a subscription with the same type and condition already exists.
`Forbidden`	If the scope is insufficient for the subscription type.

`delete_conduit(conduit_id)` `async` ¶

Deletes a conduit.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None

Parameters:

Name	Type	Description	Default
`conduit_id`	`str`	The ID of the conduit to delete.	required

Raises:

Type	Description
`TokenError`	If missing a valid app access token.
`BadRequest`	If conduit_id is invalid.
`Unauthorized`	If the token is invalid or expired.
`NotFound`	If the conduit was not found.

`delete_eventsub_subscription(subscription_id)` `async` ¶

Deletes an EventSub subscription.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	For webhook/conduit
User Access	None	For websocket

Parameters:

Name	Type	Description	Default
`subscription_id`	`str`	The ID of the subscription to delete.	required

Raises:

Type	Description
`TokenError`	If using webhooks without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the subscription_id parameter is missing or invalid.
`Unauthorized`	If the Authorization header is missing, the access token is not valid, or the Client-Id header doesn't match the client ID in the access token.
`NotFound`	If the subscription was not found.

`get_channel_chat_badges(user_id)` `async` ¶

Gets a tuple of chat badge sets for the specified broadcaster's channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The ID of the broadcaster whose channel chat badges should be retrieved.	required

Returns:

Type	Description
`Tuple[ChatBadgeSet, ...]`	A tuple of ChatBadgeSet objects representing the channel's custom chat badges

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the user_id parameter is invalid.
`Unauthorized`	If the token is invalid or expired.

`get_channel_emotes(user_id)` `async` ¶

Gets a tuple of channel-specific emotes for the specified broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The ID of the broadcaster whose channel emotes should be retrieved.	required

Returns:

Type	Description
`Tuple[ChannelEmote, ...]`	A tuple of ChannelEmote objects representing the channel's custom emotes

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the user_id parameter is invalid.
`Unauthorized`	If the token is invalid or expired.

`get_channel_information(user_ids)` `async` ¶

Gets information about one or more channels.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_ids`	`Set[str]`	The IDs of the broadcasters whose channels you want to get. Maximum of 100 broadcaster IDs. Duplicate IDs and IDs that weren't found are ignored.	required

Returns:

Type	Description
`Tuple[ChannelInfo, ...]`	A tuple of ChannelInfo objects containing information about the specified channels. The tuple is empty if the specified channels weren't found.

Raises:

Type	Description
`ValueError`	If user_ids length is not between 1 and 100.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any broadcaster ID is not valid.
`Unauthorized`	If the Authorization header is required or the OAuth token is not valid, or the ID in the Client-Id header must match the Client ID in the OAuth token.

`get_channel_stream_schedule(user_id, segment_ids=frozenset(), start_time=None, limit=25)` ¶

Gets the broadcaster's streaming schedule.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The ID of the broadcaster that owns the streaming schedule you want to get.	required
`segment_ids`	`Set[str]`	The IDs of the scheduled segments to return. Maximum of 100 IDs.	`frozenset()`
`start_time`	`Optional[datetime]`	The UTC date and time that identifies when in the broadcaster's schedule to start returning segments. If not specified, returns segments starting after the current UTC date and time. Naive datetime objects are treated as UTC.	`None`
`limit`	`Optional[int]`	The maximum number of segments to fetch.	`25`

Returns:

Type	Description
`PaginatedRequest[..., ChannelStreamSchedule]`	A paginated collection containing the broadcaster's streaming schedule.

Raises:

Type	Description
`ValueError`	If segment_ids contains more than 100 IDs.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the user_id or other parameters are invalid.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.
`NotFound`	If the broadcaster has not created a streaming schedule.

`get_channel_teams(user_id)` `async` ¶

Gets the list of Twitch teams that the broadcaster is a member of.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The ID of the broadcaster whose teams you want to get.	required

Returns:

Type	Description
`Tuple[ChannelTeam, ...]`	A tuple of ChannelTeam objects containing the teams that the broadcaster is a member of.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the user_id parameter is missing or invalid.
`Unauthorized`	If the Authorization header is required, the access token is not valid, or the ID in the Client-Id header does not match the client ID in the access token.
`NotFound`	If the broadcaster was not found.

`get_chat_settings(user_id)` `async` ¶

Gets the broadcaster's chat settings.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The ID of the broadcaster whose chat settings should be retrieved.	required

Returns:

Type	Description
`ChatSettings`	A ChatSettings object representing the broadcaster's chat settings

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the user_id parameter is invalid.
`Unauthorized`	If the token is invalid or expired.

`get_cheermotes(user_id=None)` `async` ¶

Gets a Tuple of Cheermotes that users can use to cheer Bits in any Bits-enabled channel's chat room.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_id`	`Optional[str]`	The ID of the broadcaster whose custom Cheermotes should be retrieved. If None, the response will include only global Cheermotes.	`None`

Returns:

Type	Description
`Tuple[Cheermote, ...]`	A tuple of Cheermote objects representing the available Cheermotes

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the user_id parameter is invalid.
`Unauthorized`	If the token is invalid or expired.

`get_clips_by_category_id(category_id, started_at=None, ended_at=None, is_featured=None, limit=100)` ¶

Gets video clips that were captured from streams playing a specific game.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`category_id`	`str`	An ID that identifies the game/category whose clips you want to get.	required
`started_at`	`Optional[datetime]`	The start date used to filter clips. The API returns only clips within the start and end date window. Naive datetime objects are treated as UTC.	`None`
`ended_at`	`Optional[datetime]`	The end date used to filter clips. If not specified, the time window is the start date plus one week. Naive datetime objects are treated as UTC.	`None`
`is_featured`	`Optional[bool]`	A Boolean value that determines whether the response includes featured clips. If True, returns only clips that are featured. If False, returns only clips that aren't featured. All clips are returned if this parameter is not present.	`None`
`limit`	`Optional[int]`	The maximum number of clips to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Clip]`	A paginated collection of Clip objects in descending order by view count.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the category_id or date parameters are invalid.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.
`NotFound`	If the category_id was not found.

`get_clips_by_id(clip_ids, is_featured=None)` ¶

Gets video clips by their IDs.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`clip_ids`	`Set[str]`	IDs that identify the clips to get. You may specify a maximum of 100 IDs. The API ignores duplicate IDs and IDs that aren't found.	required
`is_featured`	`Optional[bool]`	A Boolean value that determines whether the response includes featured clips.	`None`

Returns:

Type	Description
`PaginatedRequest[..., Clip]`	A paginated collection of Clip objects in the same order as the input IDs.

Raises:

Type	Description
`ValueError`	If ids contains fewer than 1 or more than 100 items.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any clip ID is invalid.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.

`get_clips_by_user_id(user_id, started_at=None, ended_at=None, is_featured=None, limit=100)` ¶

Gets video clips that were captured from a broadcaster's streams.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_id`	`str`	An ID that identifies the broadcaster whose video clips you want to get.	required
`started_at`	`Optional[datetime]`	The start date used to filter clips. The API returns only clips within the start and end date window. Naive datetime objects are treated as UTC.	`None`
`ended_at`	`Optional[datetime]`	The end date used to filter clips. If not specified, the time window is the start date plus one week. Naive datetime objects are treated as UTC.	`None`
`is_featured`	`Optional[bool]`	A Boolean value that determines whether the response includes featured clips. If True, returns only clips that are featured. If False, returns only clips that aren't featured. All clips are returned if this parameter is not present.	`None`
`limit`	`Optional[int]`	The maximum number of clips to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Clip]`	A paginated collection of Clip objects in descending order by view count.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the user_id or date parameters are invalid.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.

`get_clips_downloads(broadcaster_id, clip_ids, editor_id=None)` `async` ¶

Gets URLs to download the video file(s) for the specified clips.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	editor:manage:clips or channel:manage:clips	None
User Access	editor:manage:clips or channel:manage:clips	Token holder is editor

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`str`	The ID of the broadcaster you want to download clips for.	required
`clip_ids`	`Set[str]`	IDs that identify the clips to download. Maximum of 10 IDs.	required
`editor_id`	`Optional[str]`	The User ID of the editor for the channel. If using the broadcaster's auth token, this is the same as broadcaster_id. If None, uses broadcaster_id.	`None`

Returns:

Type	Description
`Tuple[ClipDownload, ...]`	A tuple of ClipDownload objects containing download URLs for each clip.

Raises:

Type	Description
`ValueError`	If clip_ids contains fewer than 1 or more than 10 items.
`TokenError`	If missing a valid app access token or user access token with required scope.
`BadRequest`	If any ID in broadcaster_id, editor_id, or clip_id is not valid.
`Unauthorized`	If the token is invalid, expired, or missing required scope.
`Forbidden`	If the user is not an editor for the specified broadcaster.

`get_conduit_shards(conduit_id, status=None, limit=100)` ¶

Gets the shards for a conduit.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None

Parameters:

Name	Type	Description	Default
`conduit_id`	`str`	The ID of the conduit.	required
`status`	`Optional[str]`	Filter by shard status.	`None`
`limit`	`Optional[int]`	The maximum number of shards to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., ConduitShard]`	A paginated collection of ConduitShard objects.

Raises:

Type	Description
`TokenError`	If missing a valid app access token.
`BadRequest`	If conduit_id or status is invalid.
`Unauthorized`	If the token is invalid or expired.
`NotFound`	If the conduit was not found.

`get_conduits()` `async` ¶

Gets information about the conduits for EventSub.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None

Returns:

Type	Description
`Tuple[Conduit, ...]`	A tuple of Conduit objects.

Raises:

Type	Description
`TokenError`	If missing a valid app access token.
`Unauthorized`	If the token is invalid or expired.

`get_content_classification_labels(locale='en-US')` `async` ¶

Gets information about Twitch content classification labels.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`locale`	`Literal['bg-BG', 'cs-CZ', 'da-DK', 'de-DE', 'el-GR', 'en-GB', 'en-US', 'es-ES', 'es-MX', 'fi-FI', 'fr-FR', 'hu-HU', 'it-IT', 'ja-JP', 'ko-KR', 'nl-NL', 'no-NO', 'pl-PL', 'pt-BR', 'pt-PT', 'ro-RO', 'ru-RU', 'sk-SK', 'sv-SE', 'th-TH', 'tr-TR', 'vi-VN', 'zh-CN', 'zh-TW']`	Locale for the Content Classification Labels. Possible values: 'bg-BG', 'cs-CZ', 'da-DK', 'de-DE', 'el-GR', 'en-GB', 'en-US', 'es-ES', 'es-MX', 'fi-FI', 'fr-FR', 'hu-HU', 'it-IT', 'ja-JP', 'ko-KR', 'nl-NL', 'no-NO', 'pl-PL', 'pt-BR', 'pt-PT', 'ro-RO', 'ru-RU', 'sk-SK', 'sv-SE', 'th-TH', 'tr-TR', 'vi-VN', 'zh-CN', 'zh-TW'	`'en-US'`

Returns:

Type	Description
`Tuple[ContentClassificationLabel, ...]`	A tuple of ContentClassificationLabel objects containing information about the available content classification labels.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the locale is invalid.
`Unauthorized`	If the token is invalid or expired.

`get_drops_entitlements(entitlement_ids=frozenset(), user_id=None, game_id=None, fulfillment_status=None, limit=1000)` ¶

Gets an organization's list of entitlements that have been granted to a game, a user, or both.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	Client owned by organization

Note

Entitlements are returned unsorted. Use fulfillment_status and game_id to filter results. To retrieve entitlements for a specific game, use the game_id parameter to filter results.

Parameters:

Name	Type	Description	Default
`entitlement_ids`	`Set[str]`	IDs that identify the entitlements to get. Maximum of 100 IDs.	`frozenset()`
`user_id`	`Optional[str]`	An ID that identifies a user that was granted entitlements.	`None`
`game_id`	`Optional[str]`	An ID that identifies a game that offered entitlements.	`None`
`fulfillment_status`	`Optional[Literal['CLAIMED', 'FULFILLED']]`	The entitlement's fulfillment status. Used to filter the list to only those with the specified status. Possible values are: 'CLAIMED', 'FULFILLED'.	`None`
`limit`	`Optional[int]`	The maximum total number of drops entitlements to fetch.	`1000`

Returns:

Type	Description
`PaginatedRequest[..., DropsEntitlement]`	A paginated collection of DropsEntitlement objects.

Raises:

Type	Description
`ValueError`	If ids length exceeds 100.
`TokenError`	If missing a valid app access token.
`BadRequest`	If the fulfillment_status value is not valid, or client is not associated with a known organization, or owner of client is not a member of organization.
`Unauthorized`	If Client-Id header doesn't match the Client ID in the access token, or Authorization header is missing, or access token is not valid.
`Forbidden`	If organization doesn't own the game specified in game_id, or organization doesn't own the entitlements specified in ids.

`get_emote_sets(emote_set_ids)` `async` ¶

Gets emote sets by their IDs.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`emote_set_ids`	`Set[str]`	A set of emote set IDs to retrieve. Must contain at least one ID. Maximum of 25 IDs allowed.	required

Returns:

Type	Description
`Tuple[EmoteSet, ...]`	A tuple of EmoteSet objects representing the requested emote sets

Raises:

Type	Description
`ValueError`	If emote_set_ids length is not between 1 and 25.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any emote set ID is invalid.
`Unauthorized`	If the token is invalid or expired.

`get_eventsub_subscription_by_id(subscription_id)` `async` ¶

Gets a specific EventSub subscription by its ID.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	For webhook/conduit
User Access	None	For websocket

Parameters:

Name	Type	Description	Default
`subscription_id`	`str`	Returns an array with the subscription matching the ID (as long as it is owned by the client making the request), or an empty array if there is no matching subscription.	required

Returns:

Type	Description
`Optional[Subscription]`	The EventSub subscription if found, None if not found or not owned by the client.

Raises:

Type	Description
`TokenError`	If using webhooks/conduits without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the request parameters are invalid.
`Unauthorized`	If the token is invalid or expired.
`NotFound`	If the subscription was not found.

`get_eventsub_subscriptions(limit=100)` ¶

Gets a list of all EventSub subscriptions that the client in the access token created.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	For webhook/conduit
User Access	None	For websocket

Parameters:

Name	Type	Description	Default
`limit`	`Optional[int]`	The maximum total number of EventSub subscriptions to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Subscription]`	A paginated collection of Subscription objects.

Raises:

Type	Description
`TokenError`	If using webhooks/conduits without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the request parameters are invalid.
`Unauthorized`	If the token is invalid or expired.

`get_eventsub_subscriptions_by_status(status, limit=100)` ¶

Gets a list of EventSub subscriptions filtered by status.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	For webhook/conduit
User Access	None	For websocket

Parameters:

Name	Type	Description	Default
`status`	`Literal['enabled', 'webhook_callback_verification_pending', 'webhook_callback_verification_failed', 'notification_failures_exceeded', 'authorization_revoked', 'moderator_removed', 'user_removed', 'chat_user_banned', 'version_removed', 'beta_maintenance', 'websocket_disconnected', 'websocket_failed_ping_pong', 'websocket_received_inbound_traffic', 'websocket_state_unused', 'websocket_internal_error', 'websocket_network_timeout', 'websocket_network_error', 'websocket_failed_to_reconnect']`	Filter subscriptions by its status. Possible values are: 'enabled', 'webhook_callback_verification_pending', 'webhook_callback_verification_failed', 'notification_failures_exceeded', 'authorization_revoked', 'moderator_removed', 'user_removed', 'chat_user_banned', 'version_removed', 'beta_maintenance', 'websocket_disconnected', 'websocket_failed_ping_pong', 'websocket_received_inbound_traffic', 'websocket_state_unused', 'websocket_internal_error', 'websocket_network_timeout', 'websocket_network_error', 'websocket_failed_to_reconnect'	required
`limit`	`Optional[int]`	The maximum total number of EventSub subscriptions to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Subscription]`	A paginated collection of Subscription objects.

Raises:

Type	Description
`TokenError`	If using webhooks/conduits without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the request parameters are invalid.
`Unauthorized`	If the token is invalid or expired.

`get_eventsub_subscriptions_by_type(subscriptions_type, limit=100)` ¶

Gets a list of EventSub subscriptions filtered by subscription type.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	For webhook/conduit
User Access	None	For websocket

Parameters:

Name	Type	Description	Default
`subscriptions_type`	`str`	Filter subscriptions by subscription type. For a list of subscription types, see Subscription Types.	required
`limit`	`Optional[int]`	The maximum total number of EventSub subscriptions to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Subscription]`	A paginated collection of Subscription objects.

Raises:

Type	Description
`TokenError`	If using webhooks/conduits without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the request parameters are invalid.
`Unauthorized`	If the token is invalid or expired.

`get_eventsub_subscriptions_by_user_id(user_id, limit=100)` ¶

Gets a list of EventSub subscriptions filtered by user ID.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	For webhook/conduit
User Access	None	For websocket

Parameters:

Name	Type	Description	Default
`user_id`	`str`	Filter subscriptions by user ID. The response contains subscriptions where this ID matches a user ID that you specified in the Condition object when you created the subscription.	required
`limit`	`Optional[int]`	The maximum total number of EventSub subscriptions to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Subscription]`	A paginated collection of Subscription objects.

Raises:

Type	Description
`TokenError`	If using webhooks/conduits without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the request parameters are invalid.
`Unauthorized`	If the token is invalid or expired.

`get_eventsub_subscriptions_summary()` `async` ¶

Gets summary information about your EventSub subscriptions including totals and costs.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	For webhook/conduit
User Access	None	For websocket

Returns:

Type	Description
`Tuple[int, int, int]`	A tuple containing (total, total_cost, max_total_cost): - total: The total number of subscriptions that you've created - total_cost: The sum of all of your subscription costs - max_total_cost: The maximum total cost that you're allowed to incur for all subscriptions

Raises:

Type	Description
`TokenError`	If using webhooks/conduits without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the request parameters are invalid.
`Unauthorized`	If the token is invalid or expired.

`get_extension_bits_products(extension_id, should_include_all=False)` `async` ¶

Gets the Bits products for the specified extension.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	Client ID matches extension client ID

Parameters:

Name	Type	Description	Default
`extension_id`	`str`	The ID of the extension.	required
`should_include_all`	`bool`	Whether to include expired products.	`False`

Returns:

Type	Description
`Tuple[ExtensionBitsProduct, ...]`	A tuple of ExtensionBitsProduct objects.

Raises:

Type	Description
`TokenError`	If missing token.
`BadRequest`	The ID in the Client-Id header must belong to an extension.
`Unauthorized`	If token invalid or client ID mismatch.

`get_extension_channel_configuration(broadcaster_id, extension_id)` `async` ¶

Gets the configuration of the extension on the specified channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`str`	The ID of the broadcaster (channel) whose extension configuration you want to get.	required
`extension_id`	`str`	The ID of the extension whose configuration you want to get.	required

Returns:

Type	Description
`ExtensionConfiguration`	The extension configuration on the channel.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If parameters are invalid.
`Unauthorized`	If the token is invalid or expired.
`NotFound`	If the configuration was not found.

`get_extension_live_channels(extension_id, limit=100)` ¶

Gets a list of broadcasters that are streaming live and have installed or activated the specified extension.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`extension_id`	`str`	The ID of the extension whose installed or activated channels you want to get.	required
`limit`	`Optional[int]`	The maximum number of items to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., ExtensionLiveChannel]`	A paginated collection of ExtensionLiveChannel objects.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If extension_id is missing or invalid.
`Unauthorized`	If the token is invalid or expired.

`get_extension_transactions(extension_id, transaction_ids=frozenset(), limit=100)` ¶

Gets transactions for the specified extension.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	Client ID matches extension client ID

Parameters:

Name	Type	Description	Default
`extension_id`	`str`	The ID of the extension.	required
`transaction_ids`	`Set[str]`	Transaction IDs to look up. Max 100.	`frozenset()`
`limit`	`Optional[int]`	The maximum number of items to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., ExtensionTransaction]`	A paginated collection of ExtensionTransaction objects.

Raises:

Type	Description
`ValueError`	If transaction_ids > 100.
`TokenError`	If missing token.
`BadRequest`	If extension_id or transaction_ids are invalid.
`Unauthorized`	If token invalid or client ID mismatch.

`get_games(*, game_ids=frozenset(), game_names=frozenset(), igdb_ids=frozenset())` `async` ¶

get_games(*, game_ids: Set[str]) -> Tuple[Game, ...]

get_games(*, game_names: Set[str]) -> Tuple[Game, ...]

get_games(*, igdb_ids: Set[str]) -> Tuple[Game, ...]

get_games(*, game_ids: Set[str], game_names: Set[str]) -> Tuple[Game, ...]

get_games(*, game_ids: Set[str], igdb_ids: Set[str]) -> Tuple[Game, ...]

get_games(*, game_names: Set[str], igdb_ids: Set[str]) -> Tuple[Game, ...]

get_games(*, game_ids: Set[str], game_names: Set[str], igdb_ids: Set[str]) -> Tuple[Game, ...]

Gets information about specified categories or games.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`game_ids`	`Set[str]`	The IDs of the categories or games to get. You may specify a maximum of 100 IDs. The endpoint ignores duplicate and invalid IDs or IDs that weren't found.	`frozenset()`
`game_names`	`Set[str]`	The names of the categories or games to get. The name must exactly match the category's or game's title. You may specify a maximum of 100 names. The endpoint ignores duplicate names and names that weren't found.	`frozenset()`
`igdb_ids`	`Set[str]`	The IGDB IDs of the games to get. You may specify a maximum of 100 IDs. The endpoint ignores duplicate and invalid IDs or IDs that weren't found.	`frozenset()`

Returns:

Type	Description
`Tuple[Game, ...]`	A tuple of Game objects containing information about the specified categories and games.

Raises:

Type	Description
`ValueError`	If no parameters are provided or if the combined number of IDs and names exceeds 100.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any game ID, name, or IGDB ID is invalid.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.

`get_global_chat_badges()` `async` ¶

Gets a tuple of global chat badge sets available across all Twitch channels.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Returns:

Type	Description
`Tuple[ChatBadgeSet, ...]`	A tuple of ChatBadgeSet objects representing Twitch's global chat badges

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`Unauthorized`	If the token is invalid or expired.

`get_global_emotes()` `async` ¶

Gets a tuple of global emotes available across all Twitch channels.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Returns:

Type	Description
`Tuple[GlobalEmote, ...]`	A tuple of GlobalEmote objects representing Twitch's global emotes

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`Unauthorized`	If the token is invalid or expired.

`get_shared_chat_session(user_id)` `async` ¶

Retrieves the active shared chat session for a channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The User ID of the channel broadcaster.	required

Returns:

Type	Description
`Optional[SharedChatSession]`	A SharedChatSession object representing the active shared chat session, or None if no session exists.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the user_id parameter is invalid.
`Unauthorized`	If the token is invalid or expired.

Note

Channels can be streaming together but shared chat can be enabled or disabled.

`get_streams(*, user_ids=frozenset(), user_logins=frozenset(), game_ids=frozenset(), stream_type='all', languages=frozenset())` ¶

get_streams(*, user_ids: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

get_streams(*, user_logins: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

get_streams(*, game_ids: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

get_streams(*, user_ids: Set[str], user_logins: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

get_streams(*, user_ids: Set[str], game_ids: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

get_streams(*, user_logins: Set[str], game_ids: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

get_streams(*, user_ids: Set[str], user_logins: Set[str], game_ids: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

Gets all live streams.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_ids`	`Set[str]`	User IDs used to filter the list of streams. Maximum of 100 IDs.	`frozenset()`
`user_logins`	`Set[str]`	User login names used to filter the list of streams. Maximum of 100 login names.	`frozenset()`
`game_ids`	`Set[str]`	Game (category) IDs used to filter the list of streams. Maximum of 100 IDs.	`frozenset()`
`stream_type`	`Literal['all', 'live']`	The type of stream to filter the list of streams by. Possible values are: 'all', 'live'. Default is 'all'.	`'all'`
`languages`	`Set[str]`	Language codes used to filter the list of streams. Use ISO 639-1 two-letter code (e.g., 'en' for English). Use 'other' if the language is not supported. Maximum of 100 language codes.	`frozenset()`

Returns:

Type	Description
`PaginatedRequest[..., StreamInfo]`	A paginated collection of Stream objects.

Raises:

Type	Description
`ValueError`	If any parameter set exceeds 100 items, or if no filter parameters are provided.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any user ID, login name, game ID, or language code is not valid, or if the type parameter is invalid.
`Unauthorized`	If the token is invalid or expired.

`get_team_by_id(team_id)` `async` ¶

Gets information about the specified Twitch team by ID.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`team_id`	`str`	The ID of the team to get.	required

Returns:

Type	Description
`Optional[TeamUsers]`	A TeamUsers object containing the team information and list of team members.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`Unauthorized`	If the Authorization header is required, the access token is not valid, or the ID in the Client-Id header does not match the client ID in the access token.
`NotFound`	If the specified team was not found.

`get_team_by_name(team_name)` `async` ¶

Gets information about the specified Twitch team by name.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`team_name`	`str`	The name of the team to get.	required

Returns:

Type	Description
`Optional[TeamUsers]`	A TeamUsers object containing the team information and list of team members.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`Unauthorized`	If the Authorization header is required, the access token is not valid, or the ID in the Client-Id header does not match the client ID in the access token.
`NotFound`	If the specified team was not found.

`get_top_games(limit=100)` ¶

Gets information about all top games/categories on Twitch, sorted by viewer count.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`limit`	`Optional[int]`	The maximum total number of games to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Game]`	A paginated collection of Game objects containing game information, sorted by viewer count with the most popular games first.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the limit parameter is not valid (outside 1-100 range when specified).
`Unauthorized`	If the Authorization header is required, the access token is not valid, or the ID in the Client-Id header does not match the client ID in the access token.

`get_user_authorizations(user_ids)` `async` ¶

Gets the authorization scopes that the specified user(s) have granted the application.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None

Parameters:

Name	Type	Description	Default
`user_ids`	`Set[str]`	The ID of the user(s) you want to check authorization for. Maximum of 10 IDs allowed.	required

Returns:

Type	Description
`Tuple[UserAuthorization, ...]`	A tuple of UserAuthorization objects containing user information and their authorized scopes.

Raises:

Type	Description
`ValueError`	If user_ids length exceeds 10.
`TokenError`	If missing a valid app access token.
`BadRequest`	If invalid parameters or missing parameters.
`Unauthorized`	If the access token is not valid, or Authorization header is required and must specify an app access token.
`Forbidden`	If the client-id in the header must match the client ID in the access token.

`get_user_chat_color(user_ids)` `async` ¶

Gets the color used for the user's name in chat.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_ids`	`Set[str]`	The IDs of the users whose username colors you want to get. Maximum of 100 user IDs. IDs that weren't found are ignored.	required

Returns:

Type	Description
`Tuple[UserChatColor, ...]`	A tuple of UserChatColor objects containing user information and their chat colors.

Raises:

Type	Description
`ValueError`	If user_ids length is not between 1 and 100.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any user ID is not valid.
`Unauthorized`	If the token is invalid or expired.

`get_users(*, user_ids=frozenset(), user_logins=frozenset())` `async` ¶

get_users(*, user_ids: Set[str]) -> Tuple[UserInfo, ...]

get_users(*, user_logins: Set[str]) -> Tuple[UserInfo, ...]

get_users(*, user_ids: Set[str], user_logins: Set[str]) -> Tuple[UserInfo, ...]

Gets information about one or more users.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_ids`	`Set[str]`	The IDs of the users to get. Maximum of 100 user IDs total when combined with login_names.	`frozenset()`
`user_logins`	`Set[str]`	The login names of the users to get. Maximum of 100 login names total when combined with user_ids.	`frozenset()`

Returns:

Type	Description
`Tuple[UserInfo, ...]`	A tuple of User objects containing user information.

Raises:

Type	Description
`ValueError`	If no user_ids or user_logins are provided, or if the total number exceeds 100.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any user ID or login name is not valid.
`Unauthorized`	If the token is invalid or expired.

`get_videos_by_category_id(category_id, language=None, period='all', sort='time', video_type='all', limit=100)` ¶

Gets published videos from a specific game/category.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`category_id`	`str`	A category or game ID. The response contains a maximum of 500 videos that show this content.	required
`language`	`Optional[str]`	A filter used to filter the list of videos by the language that the video owner broadcasts in. Use ISO 639-1 two-letter code (e.g., 'en' for English). Use 'other' if the language is not supported.	`None`
`period`	`Literal['all', 'day', 'month', 'week']`	A filter used to filter videos by when they were published.	`'all'`
`sort`	`Literal['time', 'trending', 'views']`	The order to sort the returned videos.	`'time'`
`video_type`	`Literal['all', 'archive', 'highlight', 'upload']`	A filter used to filter videos by type.	`'all'`
`limit`	`Optional[int]`	The maximum number of videos to fetch. Max 500	`100`

Returns:

Type	Description
`PaginatedRequest[..., Video]`	A paginated collection of Video objects.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the category_id or other filter parameters are invalid.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.
`NotFound`	If the category_id was not found.

`get_videos_by_id(video_ids)` ¶

Gets information about one or more published videos by their IDs.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`video_ids`	`Set[str]`	IDs that identify the videos to get. You may specify a maximum of 100 IDs.	required

Returns:

Type	Description
`PaginatedRequest[..., Video]`	A paginated collection of Video objects.

Raises:

Type	Description
`ValueError`	If video_ids contains fewer than 1 or more than 100 items.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any video ID is invalid.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.

`get_videos_by_user_id(user_id, language=None, period='all', sort='time', video_type='all', limit=100)` ¶

Gets published videos from a specific user.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The ID of the user whose list of videos you want to get.	required
`language`	`Optional[str]`	A filter used to filter the list of videos by the language that the video owner broadcasts in. Use ISO 639-1 two-letter code (e.g., 'en' for English). Use 'other' if the language is not supported.	`None`
`period`	`Literal['all', 'day', 'month', 'week']`	A filter used to filter videos by when they were published.	`'all'`
`sort`	`Literal['time', 'trending', 'views']`	The order to sort the returned videos.	`'time'`
`video_type`	`Literal['all', 'archive', 'highlight', 'upload']`	A filter used to filter videos by type.	`'all'`
`limit`	`Optional[int]`	The maximum number of videos to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Video]`	A paginated collection of Video objects.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the user_id or other filter parameters are invalid.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.

`remove_suspicious_user_status(target_user_id, moderator_id, broadcaster_id)` `async` ¶

Removes a suspicious user status from a chatter on the broadcaster's channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	moderator:manage:suspicious_users	None
User Access	moderator:manage:suspicious_users	Token holder is moderator

Parameters:

Name	Type	Description	Default
`target_user_id`	`str`	The ID of the user having the suspicious status removed.	required
`moderator_id`	`str`	The user ID of the moderator who is removing the status.	required
`broadcaster_id`	`str`	The ID of the broadcaster. Defaults to the current user.	required

Returns:

Type	Description
`SuspiciousUserStatus`	The suspicious user status that was removed.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid. If the status update is not allowed for this user.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`search_categories(query, limit=100)` ¶

Gets the games or categories that match the specified query.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`query`	`str`	The query to search for categories.	required
`limit`	`Optional[int]`	The maximum total number of categories to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Category]`	A paginated collection of Category objects that match the query.

Raises:

Type	Description
`ValueError`	If the query is empty.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the query parameter is missing.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.

`search_channels(query, live_only=False, limit=100)` ¶

Gets the channels that match the specified query and have streamed content within the past 6 months.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`query`	`str`	The query to search for channels.	required
`live_only`	`bool`	A Boolean value that determines whether the response includes only channels that are currently streaming live.	`False`
`limit`	`Optional[int]`	The maximum total number of channels to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., SearchChannel]`	A paginated collection of SearchChannel objects that match the query.

Raises:

Type	Description
`ValueError`	If the query is empty.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the query parameter is missing.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.

`send_chat_message(broadcaster_id, sender_id, message, reply_message_id=None, for_source_only=None)` `async` ¶

Sends a message to the broadcaster's chat room using an app access token.

Tip

This method is safer than sending messages directly as it only works in channels that have explicitly authorized your app.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	user:write:chat	Token holder can send to chat
	user:bot	Required from chatting user
	channel:bot	Required from broadcaster or moderator status

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`str`	The ID of the broadcaster whose chat room the message will be sent to.	required
`sender_id`	`str`	The ID of the user sending the message. This ID must match the user ID in the user access token.	required
`message`	`str`	The message to send. Max 500 characters. Can include emoticons using their case-sensitive names without colons (e.g., bleedPurple).	required
`reply_message_id`	`Optional[str]`	The ID of the message to reply to.	`None`
`for_source_only`	`Optional[bool]`	Whether the message is sent only to the source channel. Note: This parameter can only be set when using an App Access Token. Default behavior changes to True on May 19, 2025.	`None`

Returns:

Type	Description
`SendMessageStatus`	The status of the sent-message.

Raises:

Type	Description
`ValueError`	If message length > 500.
`TokenError`	If missing app token with required scopes.
`BadRequest`	If invalid parameters or message content.
`Unauthorized`	If the token is invalid or expired.
`Forbidden`	If not permitted to send messages to this chat room.

`update_conduit(conduit_id, shard_count)` `async` ¶

Updates a conduit's shard count.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None

Parameters:

Name	Type	Description	Default
`conduit_id`	`str`	The ID of the conduit to update.	required
`shard_count`	`int`	The new number of shards. Max 20000.	required

Returns:

Type	Description
`Conduit`	The updated Conduit.

Raises:

Type	Description
`ValueError`	If shard_count > 20000.
`TokenError`	If missing a valid app access token.
`BadRequest`	If conduit_id or shard_count is invalid.
`Unauthorized`	If the token is invalid or expired.
`NotFound`	If the conduit was not found.

`update_conduit_shards(conduit_id, shards)` `async` ¶

Updates the shards for a conduit.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None

Parameters:

Name	Type	Description	Default
`conduit_id`	`str`	The ID of the conduit.	required
`shards`	`Tuple[Dict[str, Any]]`	The list of shard updates.	required

Returns:

Type	Description
`ConduitShardUpdate`	The update status.

Raises:

Type	Description
`TokenError`	If missing a valid app access token.
`BadRequest`	If conduit_id or shards are invalid.
`Unauthorized`	If the token is invalid or expired.
`NotFound`	If the conduit was not found.

`update_drops_entitlements(fulfillment_status, entitlement_ids)` `async` ¶

Updates the Drop entitlement's fulfillment status.

The following table identifies which entitlements are updated based on the type of access token used:

App: Updates all entitlements with benefits owned by the organization in the access token.
User: Updates all entitlements owned by the user in the access token and where the benefits are owned by the organization in the access token.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	Client ID owned by organization
User Access	drops:edit	User member of organization

Parameters:

Name	Type	Description	Default
`fulfillment_status`	`Literal['CLAIMED', 'FULFILLED']`	The fulfillment status to set the entitlements to. Possible values are:	required
`entitlement_ids`	`Set[str]`	A set of IDs that identify the entitlements to update.	required

Returns:

Type	Description
`Tuple[DropsEntitlementUpdate, ...]`	A tuple of DropsEntitlementUpdate objects indicating which entitlements were successfully updated and those that weren't.

Raises:

Type	Description
`ValueError`	If entitlement_ids length exceeds 100.
`TokenError`	If missing a valid app access token or user access token. If the Client ID associated with the access token is not owned by a user who is a member of the organization that holds ownership of the game.
`BadRequest`	If the value in the fulfillment_status field is not valid. If the client in the access token is not associated with a known organization. If the owner of the client in the access token is not a member of the organization.
`Unauthorized`	If the access token is not valid. If the ID in the Client-Id header must match the Client ID in the access token.

`update_extension_bits_product(extension_id, sku, cost, name, in_development=False, display_name=None, expiration=None, is_broadcast=False)` `async` ¶

Updates or creates a Bits product for the extension.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	Client ID matches extension client ID

Parameters:

Name	Type	Description	Default
`extension_id`	`str`	The ID of the extension.	required
`sku`	`str`	The SKU of the product.	required
`cost`	`Dict[str, Any]`	The cost of the product.	required
`name`	`str`	The name of the product.	required
`in_development`	`bool`	Whether the product is in development.	`False`
`display_name`	`Optional[str]`	The display name.	`None`
`expiration`	`Optional[str]`	The expiration date.	`None`
`is_broadcast`	`bool`	Whether the product is broadcast.	`False`

Returns:

Type	Description
`ExtensionBitsProduct`	The updated or created product.

Raises:

Type	Description
`TokenError`	If missing token.
`BadRequest`	If parameters are invalid.
`Unauthorized`	If token invalid or client ID mismatch.

`UserAPI` ¶

Bases: BaseAPI

`add_blocked_term(text, broadcaster_id=None)` `async` ¶

Adds a blocked term to the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:blocked_terms	Token holder is moderator

Parameters:

Name	Type	Description	Default
`text`	`str`	The term to block.	required
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`

Returns:

Type	Description
`BlockedTerm`	The added blocked term.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or text are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`add_channel_moderator(user_id)` `async` ¶

Adds a moderator to the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:moderators	Token holder is broadcaster

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The ID of the user to add as moderator.	required

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or user_id are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.

`add_channel_vip(user_id)` `async` ¶

Adds a VIP to the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:vips	Token holder is broadcaster

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The ID of the user to add as VIP.	required

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or user_id are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.

`ban_user(user_id, broadcaster_id=None, duration=None, reason='')` `async` ¶

Bans a user in the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:banned_users	Token holder is moderator

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`
`user_id`	`str`	The ID of the user to ban.	required
`duration`	`Optional[int]`	The duration of the ban in seconds.	`None`
`reason`	`str`	The reason for the ban.	`''`

Returns:

Type	Description
`BannedUser`	The ban information.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id, user_id, duration, or reason are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`block_user(target_user_id, source_context=None, reason=None)` `async` ¶

Blocks a user.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	user:manage:blocked_users	Token holder is the user

Parameters:

Name	Type	Description	Default
`target_user_id`	`str`	The ID of the user to block.	required
`source_context`	`Optional[Literal['chat', 'whisper']]`	The source context.	`None`
`reason`	`Optional[Literal['spam', 'harassment', 'other']]`	The reason.	`None`

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If target_user_id, source_context, or reason are invalid.
`Unauthorized`	If token invalid.

`cancel_raid()` `async` ¶

Cancels a raid.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:raids	Token holder is broadcaster

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.
`NotFound`	If no pending raid.

`check_automod_status(messages)` `async` ¶

Checks if messages are held by AutoMod.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:automod	Token holder is moderator

Parameters:

Name	Type	Description	Default
`messages`	`List[Dict[str, Any]]`	The messages to check.	required

Returns:

Type	Description
`Tuple[AutoModStatusMessage, ...]`	The AutoMod status for each message.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or messages are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`check_user_subscription(broadcaster_id)` `async` ¶

Checks if a user is subscribed to the broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:read:subscriptions	Token holder is broadcaster or subscriber

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`str`	The ID of the broadcaster.	required

Returns:

Type	Description
`UserSubscription`	The subscription information.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or user_id are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster or the subscriber.
`NotFound`	If no subscription found.

`create_channel_stream_schedule_segment(start_time, timezone, is_recurring, duration=None, category_id=None, title=None)` `async` ¶

Creates a stream schedule segment.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:schedule	Token holder is broadcaster

Parameters:

Name	Type	Description	Default
`start_time`	`datetime`	The start time.	required
`timezone`	`str`	The timezone.	required
`is_recurring`	`bool`	Whether the segment is recurring.	required
`duration`	`Optional[int]`	The duration.	`None`
`category_id`	`Optional[str]`	The category ID.	`None`
`title`	`Optional[str]`	The title.	`None`

Returns:

Type	Description
`ChannelStreamSchedule`	The updated schedule.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If parameters are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.

`create_clip(broadcaster_id, has_delay=False)` `async` ¶

Creates a clip from the broadcaster's stream.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	clips:edit	Token holder is the broadcaster or editor

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`str`	The ID of the broadcaster whose stream you want to create a clip from.	required
`has_delay`	`bool`	Whether to delay the clip.	`False`

Returns:

Type	Description
`Clip`	The created clip.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster or editor.

`create_eventsub_subscription(subscription_type, subscription_version, transport, condition)` `async` ¶

Creates an EventSub subscription to receive notifications when events occur.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	Varies by type	For webhook/conduit
User Access	Varies by type	For websocket

Parameters:

Name	Type	Description	Default
`subscription_type`	`str`	The type of subscription to create. For a list of subscription types, see Subscription Types in the Twitch API documentation.	required
`subscription_version`	`str`	The version number that identifies the definition of the subscription's data.	required
`transport`	`Dict[str, Any]`	The transport details used to send the notifications. Must contain 'method' (either 'webhook' or 'websocket') and additional fields based on the method: - For webhook: 'callback' (URL) and optionally 'secret' - For websocket: 'session_id'	required
`condition`	`Dict[str, Any]`	The subscription's parameter values. Contents are determined by the subscription type.	required

Returns:

Type	Description
`Tuple[Subscription, Tuple[int, int, int]]`	A tuple containing: - The created Subscription object - A tuple of (total_subscriptions, total_cost, max_total_cost)

Raises:

Type	Description
`TokenError`	If using webhooks/conduits without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the request parameters are invalid or the subscription type/version is not supported.
`Unauthorized`	If the token is invalid or expired.
`Conflict`	If a subscription with the same type and condition already exists.
`Forbidden`	If the scope is insufficient for the subscription type.

`create_poll(title, choices, duration, bits_voting_enabled=False, bits_per_vote=0, channel_points_voting_enabled=False, channel_points_per_vote=0)` `async` ¶

Creates a poll for the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:polls	Token holder is broadcaster or moderator

Parameters:

Name	Type	Description	Default
`title`	`str`	The poll title.	required
`choices`	`List[str]`	The choices for the poll.	required
`duration`	`int`	The duration of the poll in seconds.	required
`bits_voting_enabled`	`bool`	Whether Bits voting is enabled.	`False`
`bits_per_vote`	`int`	Bits per vote.	`0`
`channel_points_voting_enabled`	`bool`	Whether Channel Points voting is enabled.	`False`
`channel_points_per_vote`	`int`	Channel Points per vote.	`0`

Returns:

Type	Description
`Poll`	The created poll.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If parameters are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster or moderator.

`create_prediction(title, outcomes, duration)` `async` ¶

Creates a prediction for the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:predictions	Token holder is broadcaster or moderator

Parameters:

Name	Type	Description	Default
`title`	`str`	The prediction title.	required
`outcomes`	`List[str]`	The outcomes for the prediction.	required
`duration`	`int`	The duration of the prediction in seconds.	required

Returns:

Type	Description
`Prediction`	The created prediction.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If parameters are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster or moderator.

`create_stream_marker(user_id=None, description=None)` `async` ¶

Creates a stream marker.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:broadcast	Token holder is broadcaster or editor

Parameters:

Name	Type	Description	Default
`user_id`	`Optional[str]`	The ID of the broadcaster.	`None`
`description`	`Optional[str]`	The description of the marker.	`None`

Returns:

Type	Description
`StreamMarker`	The created marker.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If user_id or description are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster or editor.

`delete_channel_stream_schedule_segment(segment_id)` `async` ¶

Deletes a stream schedule segment.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:schedule	Token holder is broadcaster

Parameters:

Name	Type	Description	Default
`segment_id`	`str`	The ID of the segment.	required

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or segment_id are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.
`NotFound`	If the segment was not found.

`delete_chat_messages(broadcaster_id=None, message_id=None)` `async` ¶

Deletes chat messages in the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:chat_messages	Token holder is moderator

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`
`message_id`	`Optional[str]`	The ID of the message to delete. If None, deletes all.	`None`

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or message_id are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`end_poll(poll_id, status)` `async` ¶

Ends a poll.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:polls	Token holder is broadcaster or moderator

Parameters:

Name	Type	Description	Default
`poll_id`	`str`	The ID of the poll.	required
`status`	`Literal['TERMINATED', 'ARCHIVED']`	The status to set.	required

Returns:

Type	Description
`Poll`	The ended poll.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id, poll_id, or status are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster or moderator.
`NotFound`	If the poll was not found.

`end_prediction(prediction_id, status, winning_outcome_id=None)` `async` ¶

Ends a prediction.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:predictions	Token holder is broadcaster or moderator

Parameters:

Name	Type	Description	Default
`prediction_id`	`str`	The ID of the prediction.	required
`status`	`Literal['RESOLVED', 'CANCELED']`	The status to set.	required
`winning_outcome_id`	`Optional[str]`	The ID of the winning outcome if resolved.	`None`

Returns:

Type	Description
`Prediction`	The ended prediction.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id, prediction_id, status, or winning_outcome_id are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster or moderator.
`NotFound`	If the prediction was not found.

`get_ad_schedule()` ¶

Gets the ad schedule for the broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:read:ads	Token holder is the broadcaster

Returns:

Type	Description
`PaginatedRequest[..., AdSchedule]`	A paginated collection of AdSchedule objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.

`get_automod_settings(broadcaster_id=None)` `async` ¶

Gets the AutoMod settings for the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:read:automod_settings	Token holder is moderator

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`

Returns:

Type	Description
`AutoModSettings`	The AutoMod settings.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`get_banned_users(broadcaster_id=None, user_ids=frozenset(), limit=100)` ¶

Gets the banned users in the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderation:read	Token holder is moderator

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`
`user_ids`	`Set[str]`	User IDs to filter by. Max 100.	`frozenset()`
`limit`	`Optional[int]`	The maximum number of banned users to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., BannedUser]`	A paginated collection of BannedUser objects.

Raises:

Type	Description
`ValueError`	If user_ids > 100.
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or user_ids are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`get_bits_leaderboard(count=10, period='all', started_at=None, user_id_filter=None)` `async` ¶

Gets the Bits leaderboard for the authenticated broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	bits:read	Token holder is the broadcaster

Parameters:

Name	Type	Description	Default
`count`	`int`	The number of entries to return. Max 100.	`10`
`period`	`Literal['day', 'week', 'month', 'year', 'all']`	The period for the leaderboard.	`'all'`
`started_at`	`Optional[datetime]`	The start time for the period.	`None`
`user_id_filter`	`Optional[str]`	The user ID to filter by.	`None`

Returns:

Type	Description
`Tuple[BitsLeaderboardEntry, ...]`	A tuple of BitsLeaderboardEntry objects.

Raises:

Type	Description
`ValueError`	If count > 100.
`TokenError`	If missing user token with scope.
`BadRequest`	If parameters are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.

`get_blocked_terms(broadcaster_id=None, limit=100)` ¶

Gets the blocked terms in the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:read:blocked_terms	Token holder is moderator

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`
`limit`	`Optional[int]`	The maximum number of blocked terms to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., BlockedTerm]`	A paginated collection of BlockedTerm objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`get_broadcaster_subscriptions(user_ids=frozenset(), limit=100)` ¶

Gets subscribers to the broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:read:subscriptions	Token holder is broadcaster

Parameters:

Name	Type	Description	Default
`user_ids`	`Set[str]`	User IDs to filter by. Max 100.	`frozenset()`
`limit`	`Optional[int]`	The maximum number of subscriptions to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., UserSubscription]`	A paginated collection of UserSubscription objects.

Raises:

Type	Description
`ValueError`	If user_ids > 100.
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or user_ids are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.

`get_channel_editors()` `async` ¶

Gets the channel editors for the broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:read:editors	Token holder is the broadcaster

Returns:

Type	Description
`Tuple[ChannelEditor, ...]`	A tuple of ChannelEditor objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.

`get_channel_followers(user_id=None, limit=100)` ¶

Gets the followers of the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:read:followers	Token holder is broadcaster or moderator

Parameters:

Name	Type	Description	Default
`user_id`	`Optional[str]`	The ID of the user to check if following.	`None`
`limit`	`Optional[int]`	The maximum number of followers to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., ChannelFollower]`	A paginated collection of ChannelFollower objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or user_id are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster or moderator.

`get_charity_campaign()` `async` ¶

Gets the charity campaign for the broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:read:charity	Token holder is the broadcaster

Returns:

Type	Description
`CharityCampaign`	The charity campaign.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.
`NotFound`	If no active campaign.

`get_charity_campaign_donations(limit=100)` ¶

Gets the charity donations for the broadcaster's campaign.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:read:charity	Token holder is the broadcaster

Parameters:

Name	Type	Description	Default
`limit`	`Optional[int]`	The maximum number of donations to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., CharityDonation]`	A paginated collection of CharityDonation objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.
`NotFound`	If no active campaign.

`get_chatters(broadcaster_id=None, limit=100)` ¶

Gets the list of chatters in the broadcaster's chat room.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:read:chatters	Token holder is moderator

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`
`limit`	`Optional[int]`	The maximum number of chatters to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Chatter]`	A paginated collection of Chatter objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`get_cheermotes(user_id=None)` `async` ¶

Gets a Tuple of Cheermotes that users can use to cheer Bits in any Bits-enabled channel's chat room.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_id`	`Optional[str]`	The ID of the broadcaster whose custom Cheermotes should be retrieved. If None, the response will include only global Cheermotes.	`None`

Returns:

Type	Description
`Tuple[Cheermote, ...]`	A tuple of Cheermote objects representing the available Cheermotes

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the user_id parameter is invalid.
`Unauthorized`	If the token is invalid or expired.

`get_clips_by_category_id(category_id, started_at=None, ended_at=None, is_featured=None, limit=100)` ¶

Gets video clips that were captured from streams playing a specific game.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`category_id`	`str`	An ID that identifies the game/category whose clips you want to get.	required
`started_at`	`Optional[datetime]`	The start date used to filter clips. The API returns only clips within the start and end date window. Naive datetime objects are treated as UTC.	`None`
`ended_at`	`Optional[datetime]`	The end date used to filter clips. If not specified, the time window is the start date plus one week. Naive datetime objects are treated as UTC.	`None`
`is_featured`	`Optional[bool]`	A Boolean value that determines whether the response includes featured clips. If True, returns only clips that are featured. If False, returns only clips that aren't featured. All clips are returned if this parameter is not present.	`None`
`limit`	`Optional[int]`	The maximum number of clips to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Clip]`	A paginated collection of Clip objects in descending order by view count.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the category_id or date parameters are invalid.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.
`NotFound`	If the category_id was not found.

`get_clips_by_id(clip_ids, is_featured=None)` ¶

Gets video clips by their IDs.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`clip_ids`	`Set[str]`	IDs that identify the clips to get. You may specify a maximum of 100 IDs. The API ignores duplicate IDs and IDs that aren't found.	required
`is_featured`	`Optional[bool]`	A Boolean value that determines whether the response includes featured clips.	`None`

Returns:

Type	Description
`PaginatedRequest[..., Clip]`	A paginated collection of Clip objects in the same order as the input IDs.

Raises:

Type	Description
`ValueError`	If ids contains fewer than 1 or more than 100 items.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any clip ID is invalid.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.

`get_content_classification_labels(locale='en-US')` `async` ¶

Gets information about Twitch content classification labels.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`locale`	`Literal['bg-BG', 'cs-CZ', 'da-DK', 'de-DE', 'el-GR', 'en-GB', 'en-US', 'es-ES', 'es-MX', 'fi-FI', 'fr-FR', 'hu-HU', 'it-IT', 'ja-JP', 'ko-KR', 'nl-NL', 'no-NO', 'pl-PL', 'pt-BR', 'pt-PT', 'ro-RO', 'ru-RU', 'sk-SK', 'sv-SE', 'th-TH', 'tr-TR', 'vi-VN', 'zh-CN', 'zh-TW']`	Locale for the Content Classification Labels. Possible values: 'bg-BG', 'cs-CZ', 'da-DK', 'de-DE', 'el-GR', 'en-GB', 'en-US', 'es-ES', 'es-MX', 'fi-FI', 'fr-FR', 'hu-HU', 'it-IT', 'ja-JP', 'ko-KR', 'nl-NL', 'no-NO', 'pl-PL', 'pt-BR', 'pt-PT', 'ro-RO', 'ru-RU', 'sk-SK', 'sv-SE', 'th-TH', 'tr-TR', 'vi-VN', 'zh-CN', 'zh-TW'	`'en-US'`

Returns:

Type	Description
`Tuple[ContentClassificationLabel, ...]`	A tuple of ContentClassificationLabel objects containing information about the available content classification labels.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the locale is invalid.
`Unauthorized`	If the token is invalid or expired.

`get_creator_goals()` `async` ¶

Gets the creator goals for the broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:read:goals	Token holder is the broadcaster

Returns:

Type	Description
`Tuple[CreatorGoal, ...]`	A tuple of CreatorGoal objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.

`get_emote_sets(emote_set_ids)` `async` ¶

Gets emote sets by their IDs.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`emote_set_ids`	`Set[str]`	A set of emote set IDs to retrieve. Must contain at least one ID. Maximum of 25 IDs allowed.	required

Returns:

Type	Description
`Tuple[EmoteSet, ...]`	A tuple of EmoteSet objects representing the requested emote sets

Raises:

Type	Description
`ValueError`	If emote_set_ids length is not between 1 and 25.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any emote set ID is invalid.
`Unauthorized`	If the token is invalid or expired.

`get_eventsub_subscription_by_id(subscription_id)` `async` ¶

Gets a specific EventSub subscription by its ID.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	For webhook/conduit
User Access	None	For websocket

Parameters:

Name	Type	Description	Default
`subscription_id`	`str`	Returns an array with the subscription matching the ID (as long as it is owned by the client making the request), or an empty array if there is no matching subscription.	required

Returns:

Type	Description
`Optional[Subscription]`	The EventSub subscription if found, None if not found or not owned by the client.

Raises:

Type	Description
`TokenError`	If using webhooks/conduits without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the request parameters are invalid.
`Unauthorized`	If the token is invalid or expired.
`NotFound`	If the subscription was not found.

`get_eventsub_subscriptions(limit=100)` ¶

Gets a list of all EventSub subscriptions that the client in the access token created.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	For webhook/conduit
User Access	None	For websocket

Parameters:

Name	Type	Description	Default
`limit`	`Optional[int]`	The maximum total number of EventSub subscriptions to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Subscription]`	A paginated collection of Subscription objects.

Raises:

Type	Description
`TokenError`	If using webhooks/conduits without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the request parameters are invalid.
`Unauthorized`	If the token is invalid or expired.

`get_eventsub_subscriptions_by_status(status, limit=100)` ¶

Gets a list of EventSub subscriptions filtered by status.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	For webhook/conduit
User Access	None	For websocket

Parameters:

Name	Type	Description	Default
`status`	`Literal['enabled', 'webhook_callback_verification_pending', 'webhook_callback_verification_failed', 'notification_failures_exceeded', 'authorization_revoked', 'moderator_removed', 'user_removed', 'chat_user_banned', 'version_removed', 'beta_maintenance', 'websocket_disconnected', 'websocket_failed_ping_pong', 'websocket_received_inbound_traffic', 'websocket_state_unused', 'websocket_internal_error', 'websocket_network_timeout', 'websocket_network_error', 'websocket_failed_to_reconnect']`	Filter subscriptions by its status. Possible values are: 'enabled', 'webhook_callback_verification_pending', 'webhook_callback_verification_failed', 'notification_failures_exceeded', 'authorization_revoked', 'moderator_removed', 'user_removed', 'chat_user_banned', 'version_removed', 'beta_maintenance', 'websocket_disconnected', 'websocket_failed_ping_pong', 'websocket_received_inbound_traffic', 'websocket_state_unused', 'websocket_internal_error', 'websocket_network_timeout', 'websocket_network_error', 'websocket_failed_to_reconnect'	required
`limit`	`Optional[int]`	The maximum total number of EventSub subscriptions to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Subscription]`	A paginated collection of Subscription objects.

Raises:

Type	Description
`TokenError`	If using webhooks/conduits without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the request parameters are invalid.
`Unauthorized`	If the token is invalid or expired.

`get_eventsub_subscriptions_by_type(subscriptions_type, limit=100)` ¶

Gets a list of EventSub subscriptions filtered by subscription type.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	For webhook/conduit
User Access	None	For websocket

Parameters:

Name	Type	Description	Default
`subscriptions_type`	`str`	Filter subscriptions by subscription type. For a list of subscription types, see Subscription Types.	required
`limit`	`Optional[int]`	The maximum total number of EventSub subscriptions to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Subscription]`	A paginated collection of Subscription objects.

Raises:

Type	Description
`TokenError`	If using webhooks/conduits without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the request parameters are invalid.
`Unauthorized`	If the token is invalid or expired.

`get_eventsub_subscriptions_summary()` `async` ¶

Gets summary information about your EventSub subscriptions including totals and costs.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	For webhook/conduit
User Access	None	For websocket

Returns:

Type	Description
`Tuple[int, int, int]`	A tuple containing (total, total_cost, max_total_cost): - total: The total number of subscriptions that you've created - total_cost: The sum of all of your subscription costs - max_total_cost: The maximum total cost that you're allowed to incur for all subscriptions

Raises:

Type	Description
`TokenError`	If using webhooks/conduits without an app access token, or if using WebSockets without a user access token.
`BadRequest`	If the request parameters are invalid.
`Unauthorized`	If the token is invalid or expired.

`get_extension_analytics(extension_id=None, report_type=None, started_at=None, ended_at=None, limit=100)` ¶

Gets analytics reports for extensions.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	analytics:read:extensions	Token holder owns the extension

Parameters:

Name	Type	Description	Default
`extension_id`	`Optional[str]`	The ID of the extension.	`None`
`report_type`	`Optional[str]`	The type of report.	`None`
`started_at`	`Optional[datetime]`	The start date.	`None`
`ended_at`	`Optional[datetime]`	The end date.	`None`
`limit`	`Optional[int]`	The maximum number of reports.	`100`

Returns:

Type	Description
`PaginatedRequest[..., AnalyticsReport]`	A paginated collection of AnalyticsReport objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If parameters are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user does not own the extension.

`get_extension_channel_configuration(broadcaster_id, extension_id)` `async` ¶

Gets the configuration of the extension on the specified channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`str`	The ID of the broadcaster (channel) whose extension configuration you want to get.	required
`extension_id`	`str`	The ID of the extension whose configuration you want to get.	required

Returns:

Type	Description
`ExtensionConfiguration`	The extension configuration on the channel.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If parameters are invalid.
`Unauthorized`	If the token is invalid or expired.
`NotFound`	If the configuration was not found.

`get_extension_live_channels(extension_id, limit=100)` ¶

Gets a list of broadcasters that are streaming live and have installed or activated the specified extension.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`extension_id`	`str`	The ID of the extension whose installed or activated channels you want to get.	required
`limit`	`Optional[int]`	The maximum number of items to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., ExtensionLiveChannel]`	A paginated collection of ExtensionLiveChannel objects.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If extension_id is missing or invalid.
`Unauthorized`	If the token is invalid or expired.

`get_followed_channels(broadcaster_id=None, limit=100)` ¶

Gets the channels followed by the user.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	user:read:follows	Token holder is the user

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster to check if followed.	`None`
`limit`	`Optional[int]`	The maximum number of followed channels to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., FollowedChannel]`	A paginated collection of FollowedChannel objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If user_id or broadcaster_id are invalid.
`Unauthorized`	If token invalid.

`get_game_analytics(game_id=None, report_type=None, started_at=None, ended_at=None, limit=100)` ¶

Gets analytics reports for games.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	analytics:read:games	Token holder owns the game

Parameters:

Name	Type	Description	Default
`game_id`	`Optional[str]`	The ID of the game.	`None`
`report_type`	`Optional[str]`	The type of report.	`None`
`started_at`	`Optional[datetime]`	The start date.	`None`
`ended_at`	`Optional[datetime]`	The end date.	`None`
`limit`	`Optional[int]`	The maximum number of reports.	`100`

Returns:

Type	Description
`PaginatedRequest[..., AnalyticsReport]`	A paginated collection of AnalyticsReport objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If parameters are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user does not own the game.

`get_games(*, game_ids=frozenset(), game_names=frozenset(), igdb_ids=frozenset())` `async` ¶

get_games(*, game_ids: Set[str]) -> Tuple[Game, ...]

get_games(*, game_names: Set[str]) -> Tuple[Game, ...]

get_games(*, igdb_ids: Set[str]) -> Tuple[Game, ...]

get_games(*, game_ids: Set[str], game_names: Set[str]) -> Tuple[Game, ...]

get_games(*, game_ids: Set[str], igdb_ids: Set[str]) -> Tuple[Game, ...]

get_games(*, game_names: Set[str], igdb_ids: Set[str]) -> Tuple[Game, ...]

get_games(*, game_ids: Set[str], game_names: Set[str], igdb_ids: Set[str]) -> Tuple[Game, ...]

Gets information about specified categories or games.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`game_ids`	`Set[str]`	The IDs of the categories or games to get. You may specify a maximum of 100 IDs. The endpoint ignores duplicate and invalid IDs or IDs that weren't found.	`frozenset()`
`game_names`	`Set[str]`	The names of the categories or games to get. The name must exactly match the category's or game's title. You may specify a maximum of 100 names. The endpoint ignores duplicate names and names that weren't found.	`frozenset()`
`igdb_ids`	`Set[str]`	The IGDB IDs of the games to get. You may specify a maximum of 100 IDs. The endpoint ignores duplicate and invalid IDs or IDs that weren't found.	`frozenset()`

Returns:

Type	Description
`Tuple[Game, ...]`	A tuple of Game objects containing information about the specified categories and games.

Raises:

Type	Description
`ValueError`	If no parameters are provided or if the combined number of IDs and names exceeds 100.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any game ID, name, or IGDB ID is invalid.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.

`get_global_chat_badges()` `async` ¶

Gets a tuple of global chat badge sets available across all Twitch channels.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Returns:

Type	Description
`Tuple[ChatBadgeSet, ...]`	A tuple of ChatBadgeSet objects representing Twitch's global chat badges

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`Unauthorized`	If the token is invalid or expired.

`get_global_emotes()` `async` ¶

Gets a tuple of global emotes available across all Twitch channels.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Returns:

Type	Description
`Tuple[GlobalEmote, ...]`	A tuple of GlobalEmote objects representing Twitch's global emotes

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`Unauthorized`	If the token is invalid or expired.

`get_hype_train_status()` `async` ¶

Gets the Hype Train status for the broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:read:hype_train	Token holder is the broadcaster

Returns:

Type	Description
`HypeTrainStatus`	The current Hype Train status including current train and records.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.

`get_moderators(user_ids=frozenset(), limit=100)` ¶

Gets the moderators in the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderation:read	Token holder is broadcaster or moderator

Parameters:

Name	Type	Description	Default
`user_ids`	`Set[str]`	User IDs to filter by. Max 100.	`frozenset()`
`limit`	`Optional[int]`	The maximum number of moderators to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Moderator]`	A paginated collection of Moderator objects.

Raises:

Type	Description
`ValueError`	If user_ids > 100.
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or user_ids are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster or moderator.

`get_polls(poll_ids=frozenset(), limit=20)` ¶

Gets polls for the broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:read:polls	Token holder is broadcaster or moderator

Parameters:

Name	Type	Description	Default
`poll_ids`	`Set[str]`	Poll IDs to filter by. Max 5.	`frozenset()`
`limit`	`Optional[int]`	The maximum number of polls to return.	`20`

Returns:

Type	Description
`PaginatedRequest[..., Poll]`	A paginated collection of Poll objects.

Raises:

Type	Description
`ValueError`	If poll_ids > 5.
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or poll_ids are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster or moderator.

`get_predictions(prediction_ids=frozenset(), limit=20)` ¶

Gets predictions for the broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:read:predictions	Token holder is broadcaster or moderator

Parameters:

Name	Type	Description	Default
`prediction_ids`	`Set[str]`	Prediction IDs to filter by. Max 5.	`frozenset()`
`limit`	`Optional[int]`	The maximum number of predictions to return.	`20`

Returns:

Type	Description
`PaginatedRequest[..., Prediction]`	A paginated collection of Prediction objects.

Raises:

Type	Description
`ValueError`	If prediction_ids > 5.
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or prediction_ids are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster or moderator.

`get_shield_mode_status(broadcaster_id=None)` `async` ¶

Gets the Shield Mode status for the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:read:shield_mode	Token holder is moderator

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`

Returns:

Type	Description
`ShieldModeStatus`	The Shield Mode status.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`get_stream_key()` `async` ¶

Gets the stream key for the broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:read:stream_key	Token holder is the broadcaster

Returns:

Type	Description
`StreamKey`	The stream key.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.

`get_stream_markers(user_id=None, video_id=None, limit=100)` ¶

Gets stream markers.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	user:read:broadcast	Token holder is broadcaster or editor

Parameters:

Name	Type	Description	Default
`user_id`	`Optional[str]`	The ID of the broadcaster.	`None`
`video_id`	`Optional[str]`	The ID of the video.	`None`
`limit`	`Optional[int]`	The maximum number of markers to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., StreamMarker]`	A paginated collection of StreamMarker objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If user_id or video_id are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster or editor.

`get_streams(*, user_ids=frozenset(), user_logins=frozenset(), game_ids=frozenset(), stream_type='all', languages=frozenset())` ¶

get_streams(*, user_ids: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

get_streams(*, user_logins: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

get_streams(*, game_ids: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

get_streams(*, user_ids: Set[str], user_logins: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

get_streams(*, user_ids: Set[str], game_ids: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

get_streams(*, user_logins: Set[str], game_ids: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

get_streams(*, user_ids: Set[str], user_logins: Set[str], game_ids: Set[str], stream_type: Literal['all', 'live'] = 'all', languages: Set[str] = frozenset()) -> PaginatedRequest[..., StreamInfo]

Gets all live streams.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_ids`	`Set[str]`	User IDs used to filter the list of streams. Maximum of 100 IDs.	`frozenset()`
`user_logins`	`Set[str]`	User login names used to filter the list of streams. Maximum of 100 login names.	`frozenset()`
`game_ids`	`Set[str]`	Game (category) IDs used to filter the list of streams. Maximum of 100 IDs.	`frozenset()`
`stream_type`	`Literal['all', 'live']`	The type of stream to filter the list of streams by. Possible values are: 'all', 'live'. Default is 'all'.	`'all'`
`languages`	`Set[str]`	Language codes used to filter the list of streams. Use ISO 639-1 two-letter code (e.g., 'en' for English). Use 'other' if the language is not supported. Maximum of 100 language codes.	`frozenset()`

Returns:

Type	Description
`PaginatedRequest[..., StreamInfo]`	A paginated collection of Stream objects.

Raises:

Type	Description
`ValueError`	If any parameter set exceeds 100 items, or if no filter parameters are provided.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any user ID, login name, game ID, or language code is not valid, or if the type parameter is invalid.
`Unauthorized`	If the token is invalid or expired.

`get_team_by_id(team_id)` `async` ¶

Gets information about the specified Twitch team by ID.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`team_id`	`str`	The ID of the team to get.	required

Returns:

Type	Description
`Optional[TeamUsers]`	A TeamUsers object containing the team information and list of team members.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`Unauthorized`	If the Authorization header is required, the access token is not valid, or the ID in the Client-Id header does not match the client ID in the access token.
`NotFound`	If the specified team was not found.

`get_team_by_name(team_name)` `async` ¶

Gets information about the specified Twitch team by name.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`team_name`	`str`	The name of the team to get.	required

Returns:

Type	Description
`Optional[TeamUsers]`	A TeamUsers object containing the team information and list of team members.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`Unauthorized`	If the Authorization header is required, the access token is not valid, or the ID in the Client-Id header does not match the client ID in the access token.
`NotFound`	If the specified team was not found.

`get_top_games(limit=100)` ¶

Gets information about all top games/categories on Twitch, sorted by viewer count.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`limit`	`Optional[int]`	The maximum total number of games to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Game]`	A paginated collection of Game objects containing game information, sorted by viewer count with the most popular games first.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the limit parameter is not valid (outside 1-100 range when specified).
`Unauthorized`	If the Authorization header is required, the access token is not valid, or the ID in the Client-Id header does not match the client ID in the access token.

`get_unban_requests(broadcaster_id=None, status='pending', user_id=None, limit=100)` ¶

Gets unban requests for the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:read:unban_requests	Token holder is moderator

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`
`status`	`Literal['pending', 'approved', 'denied', 'acknowledged', 'canceled']`	The status to filter by.	`'pending'`
`user_id`	`Optional[str]`	The user ID to filter by.	`None`
`limit`	`Optional[int]`	The maximum number of unban requests to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., UnbanRequest]`	A paginated collection of UnbanRequest objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or status are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`get_user_active_extensions()` `async` ¶

Gets the user's active extensions.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	user:read:extensions	Token holder is the user

Returns:

Type	Description
`ActiveUserExtension`	The active extensions.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If user_id is invalid.
`Unauthorized`	If token invalid.

`get_user_block_list(limit=100)` ¶

Gets the user's block list.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	user:read:blocked_users	Token holder is the user

Parameters:

Name	Type	Description	Default
`limit`	`Optional[int]`	The maximum number of blocked users to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., UserIdentity]`	A paginated collection of UserIdentity objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.

`get_user_extensions()` `async` ¶

Gets the user's installed extensions.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	user:read:extensions	Token holder is the user

Returns:

Type	Description
`Tuple[UserExtension, ...]`	A tuple of UserExtension objects.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`Unauthorized`	If token invalid.

`get_users(*, user_ids=frozenset(), user_logins=frozenset())` `async` ¶

get_users(*, user_ids: Set[str]) -> Tuple[UserInfo, ...]

get_users(*, user_logins: Set[str]) -> Tuple[UserInfo, ...]

get_users(*, user_ids: Set[str], user_logins: Set[str]) -> Tuple[UserInfo, ...]

Gets information about one or more users.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`user_ids`	`Set[str]`	The IDs of the users to get. Maximum of 100 user IDs total when combined with login_names.	`frozenset()`
`user_logins`	`Set[str]`	The login names of the users to get. Maximum of 100 login names total when combined with user_ids.	`frozenset()`

Returns:

Type	Description
`Tuple[UserInfo, ...]`	A tuple of User objects containing user information.

Raises:

Type	Description
`ValueError`	If no user_ids or user_logins are provided, or if the total number exceeds 100.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any user ID or login name is not valid.
`Unauthorized`	If the token is invalid or expired.

`get_videos_by_category_id(category_id, language=None, period='all', sort='time', video_type='all', limit=100)` ¶

Gets published videos from a specific game/category.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`category_id`	`str`	A category or game ID. The response contains a maximum of 500 videos that show this content.	required
`language`	`Optional[str]`	A filter used to filter the list of videos by the language that the video owner broadcasts in. Use ISO 639-1 two-letter code (e.g., 'en' for English). Use 'other' if the language is not supported.	`None`
`period`	`Literal['all', 'day', 'month', 'week']`	A filter used to filter videos by when they were published.	`'all'`
`sort`	`Literal['time', 'trending', 'views']`	The order to sort the returned videos.	`'time'`
`video_type`	`Literal['all', 'archive', 'highlight', 'upload']`	A filter used to filter videos by type.	`'all'`
`limit`	`Optional[int]`	The maximum number of videos to fetch. Max 500	`100`

Returns:

Type	Description
`PaginatedRequest[..., Video]`	A paginated collection of Video objects.

Raises:

Type	Description
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the category_id or other filter parameters are invalid.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.
`NotFound`	If the category_id was not found.

`get_videos_by_id(video_ids)` ¶

Gets information about one or more published videos by their IDs.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`video_ids`	`Set[str]`	IDs that identify the videos to get. You may specify a maximum of 100 IDs.	required

Returns:

Type	Description
`PaginatedRequest[..., Video]`	A paginated collection of Video objects.

Raises:

Type	Description
`ValueError`	If video_ids contains fewer than 1 or more than 100 items.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If any video ID is invalid.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.

`get_vips(user_ids=frozenset(), limit=100)` ¶

Gets the VIPs in the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:read:vips	Token holder is broadcaster or moderator

Parameters:

Name	Type	Description	Default
`user_ids`	`Set[str]`	User IDs to filter by. Max 100.	`frozenset()`
`limit`	`Optional[int]`	The maximum number of VIPs to return.	`100`

Returns:

Type	Description
`PaginatedRequest[..., ChannelVIP]`	A paginated collection of ChannelVIP objects.

Raises:

Type	Description
`ValueError`	If user_ids > 100.
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or user_ids are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster or moderator.

`manage_held_automod_messages(msg_id, action)` `async` ¶

Manages held AutoMod messages.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:automod_messages	Token holder is moderator

Parameters:

Name	Type	Description	Default
`msg_id`	`str`	The message ID.	required
`action`	`Literal['ALLOW', 'DENY']`	The action to take.	required

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If msg_id or action are invalid.
`Unauthorized`	If token invalid.
`NotFound`	If the message was not found.

`modify_channel_information(game_id=None, language=None, title=None, delay=None, tags=None, content_classification_labels=None, is_branded_content=None)` `async` ¶

Modifies channel information for users.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:broadcast	Token holder is the broadcaster

Parameters:

Name	Type	Description	Default
`game_id`	`Optional[str]`	The current game ID being played on the channel.	`None`
`language`	`Optional[str]`	The language of the stream.	`None`
`title`	`Optional[str]`	The title of the stream.	`None`
`delay`	`Optional[int]`	Stream delay in seconds.	`None`
`tags`	`Optional[List[str]]`	List of labels to tag the stream.	`None`
`content_classification_labels`	`Optional[Set[str]]`	List of CCL IDs.	`None`
`is_branded_content`	`Optional[bool]`	Indicates if the stream is branded content.	`None`

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If parameters are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.

`remove_blocked_term(term_id, broadcaster_id=None)` `async` ¶

Removes a blocked term from the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:blocked_terms	Token holder is moderator

Parameters:

Name	Type	Description	Default
`term_id`	`str`	The ID of the term to remove.	required
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or term_id are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.
`NotFound`	If the term was not found.

`remove_channel_moderator(user_id)` `async` ¶

Removes a moderator from the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:moderators	Token holder is broadcaster

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The ID of the user to remove as moderator.	required

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or user_id are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.
`NotFound`	If the moderator was not found.

`remove_channel_vip(user_id)` `async` ¶

Removes a VIP from the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:vips	Token holder is broadcaster

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The ID of the user to remove as VIP.	required

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or user_id are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.
`NotFound`	If the VIP was not found.

`resolve_unban_request(unban_request_id, status, resolution_text=None, broadcaster_id=None)` `async` ¶

Resolves an unban request.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:unban_requests	Token holder is moderator

Parameters:

Name	Type	Description	Default
`unban_request_id`	`str`	The ID of the unban request.	required
`status`	`Literal['approved', 'denied']`	The resolution status.	required
`resolution_text`	`Optional[str]`	The resolution text.	`None`
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`

Returns:

Type	Description
`UnbanRequest`	The resolved unban request.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id, unban_request_id, status, or resolution_text are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.
`NotFound`	If the unban request was not found.

`search_categories(query, limit=100)` ¶

Gets the games or categories that match the specified query.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`query`	`str`	The query to search for categories.	required
`limit`	`Optional[int]`	The maximum total number of categories to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., Category]`	A paginated collection of Category objects that match the query.

Raises:

Type	Description
`ValueError`	If the query is empty.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the query parameter is missing.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.

`search_channels(query, live_only=False, limit=100)` ¶

Gets the channels that match the specified query and have streamed content within the past 6 months.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	None
User Access	None	None

Parameters:

Name	Type	Description	Default
`query`	`str`	The query to search for channels.	required
`live_only`	`bool`	A Boolean value that determines whether the response includes only channels that are currently streaming live.	`False`
`limit`	`Optional[int]`	The maximum total number of channels to fetch.	`100`

Returns:

Type	Description
`PaginatedRequest[..., SearchChannel]`	A paginated collection of SearchChannel objects that match the query.

Raises:

Type	Description
`ValueError`	If the query is empty.
`TokenError`	If missing a valid app access token or user access token.
`BadRequest`	If the query parameter is missing.
`Unauthorized`	If the Authorization header is missing, the access token is invalid, or the Client-Id header doesn't match the client ID in the token.

`send_chat_announcement(message, broadcaster_id=None, color='primary')` `async` ¶

Sends an announcement to the channel's chat.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:announcements	Token holder is moderator

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`
`message`	`str`	The announcement message.	required
`color`	`Literal['blue', 'green', 'orange', 'purple', 'primary']`	The color of the announcement.	`'primary'`

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id, message, or color are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`send_chat_message(message, broadcaster_id=None, reply_message_id=None)` `async` ¶

Sends a message to the broadcaster's chat room.

Warning

Improper use can result in account termination. Recommended to use only in your own channel or with explicit moderator permission.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	user:write:chat	Token holder can send to chat, bot scopes if applicable

Parameters:

Name	Type	Description	Default
`message`	`str`	The message to send. Max 500 characters.	required
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster whose chat room the message will be sent to.	`None`
`reply_message_id`	`Optional[str]`	The ID of the message to reply to.	`None`

Returns:

Type	Description
`SendMessageStatus`	The status of the sent-message.

Raises:

Type	Description
`ValueError`	If message length > 500.
`TokenError`	If missing user token with scope.
`BadRequest`	If invalid parameters.
`Unauthorized`	If the token is invalid or expired.
`Forbidden`	If not permitted to send.

`send_shoutout(to_broadcaster_id, from_broadcaster_id=None)` `async` ¶

Sends a shoutout to another broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:shoutouts	Token holder is moderator

Parameters:

Name	Type	Description	Default
`from_broadcaster_id`	`Optional[str]`	The ID of the broadcaster sending the shoutout.	`None`
`to_broadcaster_id`	`str`	The ID of the broadcaster receiving the shoutout.	required

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster IDs are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the from_broadcaster.

`snooze_next_ad()` `async` ¶

Snoozes the next ad for the broadcaster.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:ads	Token holder is the broadcaster

Returns:

Type	Description
`AdSnooze`	The snooze information.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.

`start_commercial(length)` `async` ¶

Starts a commercial on the authenticated user's channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:edit:commercial	Token holder is partner/affiliate and live

Parameters:

Name	Type	Description	Default
`length`	`int`	The length of the commercial to run, in seconds. Twitch tries to serve a commercial that's the requested length, but it may be shorter or longer. Must be between 1 and 180 seconds.	required

Returns:

Type	Description
`StarCommercial`	The commercial start response containing length, message, and retry_after.

Raises:

Type	Description
`ValueError`	If length is not between 1 and 180 seconds.
`TokenError`	If missing a valid user access token with scope.
`BadRequest`	If the broadcaster is not streaming live, not a partner/affiliate, or is still in cooldown period from a previous commercial.
`Unauthorized`	If the token doesn't have the required scope or doesn't match the broadcaster.
`NotFound`	If the broadcaster ID was not found.

`start_raid(to_broadcaster_id)` `async` ¶

Starts a raid to another channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:raids	Token holder is broadcaster

Parameters:

Name	Type	Description	Default
`to_broadcaster_id`	`str`	The ID of the broadcaster to raid.	required

Returns:

Type	Description
`Raid`	The raid information.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_ids are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the from_broadcaster.

`unban_user(user_id, broadcaster_id=None)` `async` ¶

Unbans a user in the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:banned_users	Token holder is moderator

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`
`user_id`	`str`	The ID of the user to unban.	required

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or user_id are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.
`NotFound`	If the ban was not found.

`unblock_user(target_user_id)` `async` ¶

Unblocks a user.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	user:manage:blocked_users	Token holder is the user

Parameters:

Name	Type	Description	Default
`target_user_id`	`str`	The ID of the user to unblock.	required

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If target_user_id is invalid.
`Unauthorized`	If token invalid.
`NotFound`	If the block was not found.

`update_automod_settings(settings, broadcaster_id=None)` `async` ¶

Updates the AutoMod settings for the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:automod_settings	Token holder is moderator

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`
`settings`	`Dict[str, Any]`	The settings to update.	required

Returns:

Type	Description
`AutoModSettings`	The updated AutoMod settings.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or settings are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`update_channel_stream_schedule(is_vacation_enabled, vacation_start_time=None, vacation_end_time=None, timezone=None)` `async` ¶

Updates the channel's stream schedule.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:schedule	Token holder is broadcaster

Parameters:

Name	Type	Description	Default
`is_vacation_enabled`	`bool`	Whether vacation is enabled.	required
`vacation_start_time`	`Optional[datetime]`	Vacation start time.	`None`
`vacation_end_time`	`Optional[datetime]`	Vacation end time.	`None`
`timezone`	`Optional[str]`	The timezone.	`None`

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or other parameters are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.

`update_channel_stream_schedule_segment(segment_id, start_time=None, duration=None, category_id=None, is_canceled=None, timezone=None, title=None)` `async` ¶

Updates a stream schedule segment.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	channel:manage:schedule	Token holder is broadcaster

Parameters:

Name	Type	Description	Default
`segment_id`	`str`	The ID of the segment.	required
`start_time`	`Optional[datetime]`	The new start time.	`None`
`duration`	`Optional[int]`	The new duration.	`None`
`category_id`	`Optional[str]`	The new category ID.	`None`
`is_canceled`	`Optional[bool]`	Whether to cancel the segment.	`None`
`timezone`	`Optional[str]`	The new timezone.	`None`
`title`	`Optional[str]`	The new title.	`None`

Returns:

Type	Description
`ChannelStreamSchedule`	The updated schedule.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If parameters are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not the broadcaster.
`NotFound`	If the segment was not found.

`update_chat_color(color)` `async` ¶

Updates the color used for the user's name in chat.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	user:manage:chat_color	Token holder is the user

Parameters:

Name	Type	Description	Default
`color`	`str`	The color to set.	required

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If color is invalid.
`Unauthorized`	If token invalid.

`update_chat_settings(settings, broadcaster_id=None)` `async` ¶

Updates the channel's chat settings.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:chat_settings	Token holder is moderator

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`
`settings`	`Dict[str, Any]`	The settings to update.	required

Returns:

Type	Description
`ChatSettings`	The updated chat settings.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id or settings are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`update_drops_entitlements(fulfillment_status, entitlement_ids)` `async` ¶

Updates the Drop entitlement's fulfillment status.

The following table identifies which entitlements are updated based on the type of access token used:

App: Updates all entitlements with benefits owned by the organization in the access token.
User: Updates all entitlements owned by the user in the access token and where the benefits are owned by the organization in the access token.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
App Access	None	Client ID owned by organization
User Access	drops:edit	User member of organization

Parameters:

Name	Type	Description	Default
`fulfillment_status`	`Literal['CLAIMED', 'FULFILLED']`	The fulfillment status to set the entitlements to. Possible values are:	required
`entitlement_ids`	`Set[str]`	A set of IDs that identify the entitlements to update.	required

Returns:

Type	Description
`Tuple[DropsEntitlementUpdate, ...]`	A tuple of DropsEntitlementUpdate objects indicating which entitlements were successfully updated and those that weren't.

Raises:

Type	Description
`ValueError`	If entitlement_ids length exceeds 100.
`TokenError`	If missing a valid app access token or user access token. If the Client ID associated with the access token is not owned by a user who is a member of the organization that holds ownership of the game.
`BadRequest`	If the value in the fulfillment_status field is not valid. If the client in the access token is not associated with a known organization. If the owner of the client in the access token is not a member of the organization.
`Unauthorized`	If the access token is not valid. If the ID in the Client-Id header must match the Client ID in the access token.

`update_shield_mode_status(is_active, broadcaster_id=None)` `async` ¶

Updates the Shield Mode status for the channel.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:shield_mode	Token holder is moderator

Parameters:

Name	Type	Description	Default
`is_active`	`bool`	Whether to activate Shield Mode.	required
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`

Returns:

Type	Description
`ShieldModeStatus`	The Shield Mode status.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id is invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`update_user(description=None)` `async` ¶

Updates the user's information.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	user:edit	Token holder is the user

Parameters:

Name	Type	Description	Default
`description`	`Optional[str]`	The new description.	`None`

Returns:

Type	Description
`UserInfo`	The updated user information.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If description is invalid.
`Unauthorized`	If token invalid.

`update_user_extensions(data)` `async` ¶

Updates the user's active extensions.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	user:edit:extensions	Token holder is the user

Parameters:

Name	Type	Description	Default
`data`	`Dict[str, Any]`	The extension configuration data.	required

Returns:

Type	Description
`UserActiveExtensionUpdate`	The updated active extensions.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If data is invalid.
`Unauthorized`	If token invalid.

`warn_chat_user(user_id, reason, broadcaster_id=None)` `async` ¶

Warns a user in chat.

Token and Authorization Requirements::

Token Type	Required Scopes	Authorization Requirements
User Access	moderator:manage:warnings	Token holder is moderator

Parameters:

Name	Type	Description	Default
`broadcaster_id`	`Optional[str]`	The ID of the broadcaster.	`None`
`user_id`	`str`	The ID of the user to warn.	required
`reason`	`str`	The reason for the warning.	required

Returns:

Type	Description
`WarnReason`	The warn status.

Raises:

Type	Description
`TokenError`	If missing user token with scope.
`BadRequest`	If broadcaster_id, user_id, or reason are invalid.
`Unauthorized`	If token invalid.
`Forbidden`	If the token user is not a moderator for the broadcaster.

`PaginatedRequest` ¶

Paginated request handler for API endpoints with cursor-based pagination.

Attributes:

Name	Type	Description
`cursor`	`Optional[str]`	Current pagination cursor for the next request.

Examples:

Fetch all items::

followers = await user.get_channel_followers()

Iterate one by one::

async for follower in user.get_channel_followers():
    ...

Manual pagination::

paginator = user.get_channel_followers()
page = await paginator.next()

`done` `property` ¶

Whether pagination has completed and no more pages are available.

`fetched_count` `property` ¶

Total number of items fetched across all pages so far.

`aiter()` ¶

Return an async iterator for the paginator.

`await()` ¶

Allow the paginator to be awaited directly.

`call()` `async` ¶

Fetch all available pages and return as a single tuple.

Continues fetching pages until either no more data is available or the fetch_limit is reached.

Returns:

Type	Description
`Tuple[R, ...]`	All items from all fetched pages.

Examples:

Fetch all available items::

paginator = PaginatedRequest(http.get, route, max_first=100)
all_items = await paginator()

Fetch with limit::

paginator = PaginatedRequest(http.get, route, max_first=100, fetch_limit=500)
limited_items = await paginator()  # Max 500 items

`before()` `async` ¶

Fetch the previous page of items.

Warning

Most Twitch API endpoints do not support backward pagination. This method is provided for completeness but may not work with all endpoints.

Returns:

Type	Description
`Tuple[R, ...]`	Tuple of items from the previous page.

Raises:

Type	Description
`BadRequest`	If the endpoint doesn't support backward pagination.

Examples:

Backward pagination (if supported)::

paginator = PaginatedRequest(http.get, route, max_first=50)
previous_page = await paginator.before()

`next()` `async` ¶

Fetch the next page of items.

Returns:

Type	Description
`Tuple[R, ...]`	Tuple of items from the next page. Empty tuple if no more pages.

Classes

AppAPI ¶

add_suspicious_user_status(target_user_id, moderator_id, broadcaster_id, status) async ¶

create_clip_from_vod(broadcaster_id, vod_id, vod_offset, title, editor_id=None, duration=None) async ¶

create_conduit(shard_count) async ¶

create_eventsub_subscription(subscription_type, subscription_version, transport, condition) async ¶

delete_conduit(conduit_id) async ¶

delete_eventsub_subscription(subscription_id) async ¶

get_channel_chat_badges(user_id) async ¶

get_channel_emotes(user_id) async ¶

get_channel_information(user_ids) async ¶

get_channel_stream_schedule(user_id, segment_ids=frozenset(), start_time=None, limit=25) ¶

get_channel_teams(user_id) async ¶

get_chat_settings(user_id) async ¶

get_cheermotes(user_id=None) async ¶

get_clips_by_category_id(category_id, started_at=None, ended_at=None, is_featured=None, limit=100) ¶

get_clips_by_id(clip_ids, is_featured=None) ¶

get_clips_by_user_id(user_id, started_at=None, ended_at=None, is_featured=None, limit=100) ¶

get_clips_downloads(broadcaster_id, clip_ids, editor_id=None) async ¶

get_conduit_shards(conduit_id, status=None, limit=100) ¶

get_conduits() async ¶

get_content_classification_labels(locale='en-US') async ¶

get_drops_entitlements(entitlement_ids=frozenset(), user_id=None, game_id=None, fulfillment_status=None, limit=1000) ¶

get_emote_sets(emote_set_ids) async ¶

get_eventsub_subscription_by_id(subscription_id) async ¶

get_eventsub_subscriptions(limit=100) ¶

get_eventsub_subscriptions_by_status(status, limit=100) ¶

get_eventsub_subscriptions_by_type(subscriptions_type, limit=100) ¶

get_eventsub_subscriptions_by_user_id(user_id, limit=100) ¶

get_eventsub_subscriptions_summary() async ¶

get_extension_bits_products(extension_id, should_include_all=False) async ¶

get_extension_channel_configuration(broadcaster_id, extension_id) async ¶

get_extension_live_channels(extension_id, limit=100) ¶

get_extension_transactions(extension_id, transaction_ids=frozenset(), limit=100) ¶

get_games(*, game_ids=frozenset(), game_names=frozenset(), igdb_ids=frozenset()) async ¶

get_global_chat_badges() async ¶

get_global_emotes() async ¶

get_shared_chat_session(user_id) async ¶

get_streams(*, user_ids=frozenset(), user_logins=frozenset(), game_ids=frozenset(), stream_type='all', languages=frozenset()) ¶

get_team_by_id(team_id) async ¶

get_team_by_name(team_name) async ¶

get_top_games(limit=100) ¶

get_user_authorizations(user_ids) async ¶

get_user_chat_color(user_ids) async ¶

get_users(*, user_ids=frozenset(), user_logins=frozenset()) async ¶

get_videos_by_category_id(category_id, language=None, period='all', sort='time', video_type='all', limit=100) ¶

get_videos_by_id(video_ids) ¶

get_videos_by_user_id(user_id, language=None, period='all', sort='time', video_type='all', limit=100) ¶

remove_suspicious_user_status(target_user_id, moderator_id, broadcaster_id) async ¶

search_categories(query, limit=100) ¶

search_channels(query, live_only=False, limit=100) ¶

send_chat_message(broadcaster_id, sender_id, message, reply_message_id=None, for_source_only=None) async ¶

update_conduit(conduit_id, shard_count) async ¶

update_conduit_shards(conduit_id, shards) async ¶

update_drops_entitlements(fulfillment_status, entitlement_ids) async ¶

update_extension_bits_product(extension_id, sku, cost, name, in_development=False, display_name=None, expiration=None, is_broadcast=False) async ¶

UserAPI ¶

add_blocked_term(text, broadcaster_id=None) async ¶

add_channel_moderator(user_id) async ¶

add_channel_vip(user_id) async ¶

ban_user(user_id, broadcaster_id=None, duration=None, reason='') async ¶

block_user(target_user_id, source_context=None, reason=None) async ¶

cancel_raid() async ¶

check_automod_status(messages) async ¶

check_user_subscription(broadcaster_id) async ¶

create_channel_stream_schedule_segment(start_time, timezone, is_recurring, duration=None, category_id=None, title=None) async ¶

create_clip(broadcaster_id, has_delay=False) async ¶

create_eventsub_subscription(subscription_type, subscription_version, transport, condition) async ¶

create_poll(title, choices, duration, bits_voting_enabled=False, bits_per_vote=0, channel_points_voting_enabled=False, channel_points_per_vote=0) async ¶

create_prediction(title, outcomes, duration) async ¶

create_stream_marker(user_id=None, description=None) async ¶

delete_channel_stream_schedule_segment(segment_id) async ¶

delete_chat_messages(broadcaster_id=None, message_id=None) async ¶

end_poll(poll_id, status) async ¶

end_prediction(prediction_id, status, winning_outcome_id=None) async ¶

get_ad_schedule() ¶

get_automod_settings(broadcaster_id=None) async ¶

get_banned_users(broadcaster_id=None, user_ids=frozenset(), limit=100) ¶

get_bits_leaderboard(count=10, period='all', started_at=None, user_id_filter=None) async ¶

get_blocked_terms(broadcaster_id=None, limit=100) ¶

`AppAPI` ¶

`add_suspicious_user_status(target_user_id, moderator_id, broadcaster_id, status)` `async` ¶

`create_clip_from_vod(broadcaster_id, vod_id, vod_offset, title, editor_id=None, duration=None)` `async` ¶

`create_conduit(shard_count)` `async` ¶

`create_eventsub_subscription(subscription_type, subscription_version, transport, condition)` `async` ¶

`delete_conduit(conduit_id)` `async` ¶

`delete_eventsub_subscription(subscription_id)` `async` ¶

`get_channel_chat_badges(user_id)` `async` ¶

`get_channel_emotes(user_id)` `async` ¶

`get_channel_information(user_ids)` `async` ¶

`get_channel_stream_schedule(user_id, segment_ids=frozenset(), start_time=None, limit=25)` ¶

`get_channel_teams(user_id)` `async` ¶

`get_chat_settings(user_id)` `async` ¶

`get_cheermotes(user_id=None)` `async` ¶

`get_clips_by_category_id(category_id, started_at=None, ended_at=None, is_featured=None, limit=100)` ¶

`get_clips_by_id(clip_ids, is_featured=None)` ¶

`get_clips_by_user_id(user_id, started_at=None, ended_at=None, is_featured=None, limit=100)` ¶

`get_clips_downloads(broadcaster_id, clip_ids, editor_id=None)` `async` ¶

`get_conduit_shards(conduit_id, status=None, limit=100)` ¶

`get_conduits()` `async` ¶

`get_content_classification_labels(locale='en-US')` `async` ¶

`get_drops_entitlements(entitlement_ids=frozenset(), user_id=None, game_id=None, fulfillment_status=None, limit=1000)` ¶

`get_emote_sets(emote_set_ids)` `async` ¶

`get_eventsub_subscription_by_id(subscription_id)` `async` ¶

`get_eventsub_subscriptions(limit=100)` ¶

`get_eventsub_subscriptions_by_status(status, limit=100)` ¶

`get_eventsub_subscriptions_by_type(subscriptions_type, limit=100)` ¶

`get_eventsub_subscriptions_by_user_id(user_id, limit=100)` ¶

`get_eventsub_subscriptions_summary()` `async` ¶

`get_extension_bits_products(extension_id, should_include_all=False)` `async` ¶

`get_extension_channel_configuration(broadcaster_id, extension_id)` `async` ¶

`get_extension_live_channels(extension_id, limit=100)` ¶

`get_extension_transactions(extension_id, transaction_ids=frozenset(), limit=100)` ¶

`get_games(*, game_ids=frozenset(), game_names=frozenset(), igdb_ids=frozenset())` `async` ¶

`get_global_chat_badges()` `async` ¶

`get_global_emotes()` `async` ¶

`get_shared_chat_session(user_id)` `async` ¶

`get_streams(*, user_ids=frozenset(), user_logins=frozenset(), game_ids=frozenset(), stream_type='all', languages=frozenset())` ¶

`get_team_by_id(team_id)` `async` ¶

`get_team_by_name(team_name)` `async` ¶

`get_top_games(limit=100)` ¶

`get_user_authorizations(user_ids)` `async` ¶

`get_user_chat_color(user_ids)` `async` ¶

`get_users(*, user_ids=frozenset(), user_logins=frozenset())` `async` ¶

`get_videos_by_category_id(category_id, language=None, period='all', sort='time', video_type='all', limit=100)` ¶

`get_videos_by_id(video_ids)` ¶

`get_videos_by_user_id(user_id, language=None, period='all', sort='time', video_type='all', limit=100)` ¶

`remove_suspicious_user_status(target_user_id, moderator_id, broadcaster_id)` `async` ¶

`search_categories(query, limit=100)` ¶

`search_channels(query, live_only=False, limit=100)` ¶

`send_chat_message(broadcaster_id, sender_id, message, reply_message_id=None, for_source_only=None)` `async` ¶

`update_conduit(conduit_id, shard_count)` `async` ¶

`update_conduit_shards(conduit_id, shards)` `async` ¶

`update_drops_entitlements(fulfillment_status, entitlement_ids)` `async` ¶

`update_extension_bits_product(extension_id, sku, cost, name, in_development=False, display_name=None, expiration=None, is_broadcast=False)` `async` ¶

`UserAPI` ¶

`add_blocked_term(text, broadcaster_id=None)` `async` ¶

`add_channel_moderator(user_id)` `async` ¶

`add_channel_vip(user_id)` `async` ¶

`ban_user(user_id, broadcaster_id=None, duration=None, reason='')` `async` ¶

`block_user(target_user_id, source_context=None, reason=None)` `async` ¶

`cancel_raid()` `async` ¶

`check_automod_status(messages)` `async` ¶

`check_user_subscription(broadcaster_id)` `async` ¶

`create_channel_stream_schedule_segment(start_time, timezone, is_recurring, duration=None, category_id=None, title=None)` `async` ¶

`create_clip(broadcaster_id, has_delay=False)` `async` ¶

`create_eventsub_subscription(subscription_type, subscription_version, transport, condition)` `async` ¶

`create_poll(title, choices, duration, bits_voting_enabled=False, bits_per_vote=0, channel_points_voting_enabled=False, channel_points_per_vote=0)` `async` ¶

`create_prediction(title, outcomes, duration)` `async` ¶

`create_stream_marker(user_id=None, description=None)` `async` ¶

`delete_channel_stream_schedule_segment(segment_id)` `async` ¶

`delete_chat_messages(broadcaster_id=None, message_id=None)` `async` ¶

`end_poll(poll_id, status)` `async` ¶

`end_prediction(prediction_id, status, winning_outcome_id=None)` `async` ¶

`get_ad_schedule()` ¶

`get_automod_settings(broadcaster_id=None)` `async` ¶

`get_banned_users(broadcaster_id=None, user_ids=frozenset(), limit=100)` ¶

`get_bits_leaderboard(count=10, period='all', started_at=None, user_id_filter=None)` `async` ¶

`get_blocked_terms(broadcaster_id=None, limit=100)` ¶

`get_broadcaster_subscriptions(user_ids=frozenset(), limit=100)` ¶