KickClient

The main client class for interacting with the Kick API.

kickpy.client.KickClient(client_id, client_secret)

authenticate(scopes, redirect_uri=None, port=3000, timeout=300) async

Authenticate with Kick using OAuth 2.1 + PKCE.

Opens the user's browser to authorize, captures the callback on a local server, and exchanges the code for tokens.

Parameters:

Name	Type	Description	Default
scopes	list[Scope | str]	The scopes to request.	required
redirect_uri	str | None	The redirect URI. Defaults to http://127.0.0.1:{port}/callback.	None
port	int	The local port for the callback server. Defaults to 3000.	3000
timeout	float	Maximum seconds to wait for the user to authorize. Defaults to 300 (5 minutes).	300

set_user_token(access_token, refresh_token, expires_in, scope)

Manually set a user token for users who handle OAuth externally.

Parameters:

Name	Type	Description	Default
access_token	str	The access token.	required
refresh_token	str	The refresh token.	required
expires_in	int	Seconds until the token expires.	required
scope	str	The scopes granted.	required

introspect_token(*, use_user_token=False) async

Check whether the current access token is valid and get information about it.

Uses the POST https://id.kick.com/oauth/token/introspect endpoint.

Parameters:

Name	Type	Description	Default
use_user_token	bool	Introspect the user token instead of the app token. Defaults to False.	False

Returns:

Type	Description
TokenIntrospection	The token information. active is False when the token is not valid.

close() async

Close the client and all sessions.

fetch_public_key() async

Get the public key of the Kick.com API.

Returns:

Type	Description
bytes	The public key data.

fetch_user(user_id) async

Get a user by their ID.

Parameters:

Name	Type	Description	Default
user_id	int	The ID of the user to get.	required

Returns:

Type	Description
User	The user data.

fetch_channel(user_id=None, slug=None) async

Get a channel by the broadcaster user ID or slug.

Parameters:

Name	Type	Description	Default
user_id	int | None	The broadcaster user ID.	None
slug	str | None	The broadcaster user slug.	None

Returns:

Type	Description
Channel	The channel data.

update_channel(*, category_id=None, stream_title=None, custom_tags=None) async

Update channel metadata. Requires channel:write scope.

At least one parameter must be provided.

Parameters:

Name	Type	Description	Default
category_id	int | None	The new category ID.	None
stream_title	str | None	The new stream title.	None
custom_tags	list[str] | None	The new custom tags (max 10).	None

fetch_livestreams_v2(*, category_ids=None, language_codes=None, limit=100, cursor=None) async

Get active livestreams using the paginated v2 endpoint.

Livestreams are sorted from oldest to newest. Use the returned page's next_cursor to fetch the following page.

Parameters:

Name	Type	Description	Default
category_ids	list[int] | None	Only return livestreams in these categories (max 25).	None
language_codes	list[str] | None	Only return livestreams in these languages, as BCP 47 tags (max 25).	None
limit	int	Results per page (1-1000, default 100).	100
cursor	str | None	Pagination cursor from a previous page.	None

Returns:

Type	Description
Page[LiveStreamV2]	A page of livestreams.

fetch_user_livestreams(user_ids) async

Get the active livestreams of the given broadcasters.

Users that are not currently live are simply absent from the result.

Parameters:

Name	Type	Description	Default
user_ids	int | list[int]	One or more broadcaster user IDs (max 100).	required

Returns:

Type	Description
list[LiveStreamV2]	The active livestreams.

fetch_livestream_stats() async

Get global livestream statistics.

Returns:

Type	Description
LivestreamStats	The livestream stats.

fetch_livestream(broadcaster_user_id) async

Get livestream by the broadcaster user ID.

.. deprecated:: 1.1 The v1 livestreams endpoint is deprecated by Kick. Use :meth:fetch_user_livestreams instead.

Parameters:

Name	Type	Description	Default
broadcaster_user_id	int	The broadcaster user ID to get livestream from.	required

Returns:

Type	Description
LiveStream	The livestream data.

fetch_livestreams(broadcaster_user_id=None, category_id=None, language=None, limit=None, sort='viewer_count') async

Get livestreams.

.. deprecated:: 1.1 The v1 livestreams endpoint is deprecated by Kick. Use :meth:fetch_livestreams_v2 or :meth:fetch_user_livestreams instead.

Parameters:

Name	Type	Description	Default
broadcaster_user_id	int | list[int] | None	One or more broadcaster user IDs (up to 50).	None
category_id	int | None	The category ID to filter by.	None
language	str | None	The language to filter by.	None
limit	int | None	The maximum number of results (1-100, default 25).	None
sort	str	Sort order. Either 'viewer_count' or 'started_at'.	'viewer_count'

Returns:

Type	Description
list[LiveStream]	A list of livestream data.

fetch_categories(query=None, *, name=None, tag=None, category_id=None, cursor=None, limit=25) async

Get categories using the v2 endpoint.

Use the returned page's next_cursor to fetch the following page.

Parameters:

Name	Type	Description	Default
query	str | None	Shorthand for searching by name. Equivalent to name=[query].	None
name	list[str] | None	Category names to search for.	None
tag	list[str] | None	Category tags to filter by.	None
category_id	list[int] | None	Category IDs to filter by.	None
cursor	str | None	Pagination cursor.	None
limit	int	Results limit (1-1000, default 25).	25

Returns:

Type	Description
Page[Category]	A page of categories.

send_chat_message(content, message_type='bot', broadcaster_user_id=None, reply_to_message_id=None) async

Send a chat message. Requires chat:write scope.

Parameters:

Name	Type	Description	Default
content	str	The message text (max 500 characters).	required
message_type	str	The sending mode: 'user' or 'bot'.	'bot'
broadcaster_user_id	int | None	Required when message_type is 'user'. The channel to send to.	None
reply_to_message_id	str | None	Optional message ID to reply to.	None

Returns:

Type	Description
ChatResponse	The response containing is_sent and message_id.

delete_chat_message(message_id) async

Delete a chat message. Requires moderation:chat_message:manage scope.

Parameters:

Name	Type	Description	Default
message_id	str	The ID of the message to delete.	required

ban_user(broadcaster_user_id, user_id, *, duration=None, reason=None) async

Ban or timeout a user. Requires moderation:ban scope.

Parameters:

Name	Type	Description	Default
broadcaster_user_id	int	The channel to ban in.	required
user_id	int	The user to ban.	required
duration	int | None	Timeout duration in minutes (1-10080). Omit for permanent ban.	None
reason	str | None	The ban/timeout reason (max 100 characters).	None

unban_user(broadcaster_user_id, user_id) async

Unban a user or remove a timeout. Requires moderation:ban scope.

Parameters:

Name	Type	Description	Default
broadcaster_user_id	int	The channel to unban in.	required
user_id	int	The user to unban.	required

fetch_channel_rewards() async

Get channel point rewards. Requires channel:rewards:read scope.

Returns:

Type	Description
list[ChannelReward]	A list of channel rewards.

create_channel_reward(cost, title, *, background_color=None, description=None, is_enabled=None, is_user_input_required=None, should_redemptions_skip_request_queue=None) async

Create a channel point reward. Requires channel:rewards:write scope.

Parameters:

Name	Type	Description	Default
cost	int	The cost in channel points (min 1).	required
title	str	The reward title (max 50 characters).	required
background_color	str | None	Hex color (default #00e701).	None
description	str | None	The reward description (max 200 characters).	None
is_enabled	bool | None	Whether the reward is enabled (default True).	None
is_user_input_required	bool | None	Whether user input is required (default False).	None
should_redemptions_skip_request_queue	bool | None	Whether redemptions skip the queue (default False).	None

Returns:

Type	Description
ChannelReward	The created reward.

update_channel_reward(reward_id, *, background_color=None, cost=None, description=None, is_enabled=None, is_paused=None, is_user_input_required=None, should_redemptions_skip_request_queue=None, title=None) async

Update a channel point reward. Requires channel:rewards:write scope.

Only the app that created the reward can update it.

Parameters:

Name	Type	Description	Default
reward_id	str	The reward ID (ULID).	required
background_color	str | None	Hex color.	None
cost	int | None	The cost in channel points.	None
description	str | None	The reward description.	None
is_enabled	bool | None	Whether the reward is enabled.	None
is_paused	bool | None	Whether the reward is paused.	None
is_user_input_required	bool | None	Whether user input is required.	None
should_redemptions_skip_request_queue	bool | None	Whether redemptions skip the queue.	None
title	str | None	The reward title.	None

Returns:

Type	Description
ChannelReward	The updated reward.

delete_channel_reward(reward_id) async

Delete a channel point reward. Requires channel:rewards:write scope.

Only the app that created the reward can delete it.

Parameters:

Name	Type	Description	Default
reward_id	str	The reward ID (ULID).	required

fetch_reward_redemptions(*, reward_id=None, status=None, ids=None, cursor=None) async

Get reward redemptions. Requires channel:rewards:read scope.

Use the returned page's next_cursor to fetch the following page.

Parameters:

Name	Type	Description	Default
reward_id	str | None	Filter by specific reward ID.	None
status	str | None	Filter by status: 'pending', 'accepted', or 'rejected'.	None
ids	list[str] | None	Specific redemption IDs (cannot combine with other filters).	None
cursor	str | None	Pagination cursor.	None

Returns:

Type	Description
Page[RedemptionsByReward]	A page of redemptions grouped by reward.

accept_reward_redemptions(ids) async

Accept pending reward redemptions. Requires channel:rewards:write scope.

Parameters:

Name	Type	Description	Default
ids	list[str]	Redemption IDs to accept (1-25, must be unique).	required

Returns:

Type	Description
list[FailedRedemption]	A list of failed redemptions (empty if all succeeded).

reject_reward_redemptions(ids) async

Reject pending reward redemptions. Requires channel:rewards:write scope.

Parameters:

Name	Type	Description	Default
ids	list[str]	Redemption IDs to reject (1-25, must be unique).	required

Returns:

Type	Description
list[FailedRedemption]	A list of failed redemptions (empty if all succeeded).

fetch_kicks_leaderboard(top=10) async

Get the KICKs leaderboard. Requires kicks:read scope.

Parameters:

Name	Type	Description	Default
top	int	Number of top entries (1-100, default 10).	10

Returns:

Type	Description
KicksLeaderboard	The leaderboard with lifetime, month, and week rankings.

fetch_ad_break_status() async

Get the ad break status of the authenticated broadcaster's channel.

Requires ads:read or ads:write scope.

Returns:

Type	Description
AdBreakStatus	Opt-in state, remaining ad breaks, limits and recent ad breaks.

create_ad_break(break_duration_seconds, *, ad_break_id=None) async

Run an ad break on the authenticated broadcaster's channel.

Requires ads:write scope. The channel must be live, enrolled in ads (see :meth:enroll_in_ads) and have no ad break already active.

Parameters:

Name	Type	Description	Default
break_duration_seconds	int	Length of the ad break in seconds (7-300).	required
ad_break_id	str | None	Client-generated UUID identifying this ad break. A random one is generated when omitted.	None

Returns:

Type	Description
AdBreak	The accepted ad break and the number of remaining ad breaks.

Raises:

Type	Description
BadRequest	With code set to e.g. CHANNEL_IS_NOT_LIVE, CHANNEL_NOT_OPTED_IN, ADS_BLOCKED or AUTO_ADS_ACTIVE.
Conflict	With code AD_BREAK_ACTIVE when an ad break is already running.
Ratelimited	With code MAX_AD_BREAKS_REACHED.

enroll_in_ads() async

Enroll the authenticated broadcaster's channel in ads.

Requires ads:write scope. The channel must be offline and must have streamed at least once.

Raises:

Type	Description
BadRequest	With code CHANNEL_IS_LIVE or CHANNEL_NEVER_STREAMED.
NotFound	With code CHANNEL_NOT_FOUND.

fetch_events_subscriptions() async

Get event subscriptions.

Returns:

Type	Description
list[EventsSubscription]	A list of EventsSubscription data.

subscribe_to_event(event_type, user_id) async

Subscribe to an event.

Parameters:

Name	Type	Description	Default
event_type	WebhookEvent	The event type to subscribe to.	required
user_id	int	The user ID to subscribe to.	required

Returns:

Type	Description
EventsSubscriptionCreated	The created event subscription if successful, otherwise None.

unsubscribe_from_event(subscription_id) async

Unsubscribe from an event.

Parameters:

Name	Type	Description	Default
subscription_id	str	The subscription ID to unsubscribe from.	required