TwitchAdsRequests

Inherits: TwitchRequestBase < RefCounted < Object

Twitch Ads API for managing commercials and ad schedules.

Description

TwitchAdsRequests provides methods for starting commercials, getting ad schedules, and managing ad breaks on Twitch channels. Requires appropriate OAuth scopes (channel:edit:commercial for starting commercials). Access through TwitchAPI.get_ads().

Tutorials

• Twitch API documentation

• TwitchAPI Developer Examples

Methods

void	get_ad_schedule(broadcaster_id: String)
void	snooze_next_ad(broadcaster_id: String)
void	start_commercial(broadcaster_id: String, length: int)

---

Method Descriptions

void get_ad_schedule(broadcaster_id: String) 🔗

Gets the broadcaster's ad schedule information including snooze count, next ad time, and preroll-free time. Results are returned via the TwitchAPI.request_completed signal with signal_name "ad_schedule_received".

Response includes: snooze_count, snooze_refresh_at, next_ad_at, duration, last_ad_at, preroll_free_time.

TwitchAPI.get_ads().get_ad_schedule("broadcaster_id")
# Response: {"data": [{"snooze_count": 1, "snooze_refresh_at": "2025-10-16T12:00:00Z", "next_ad_at": "2025-10-16T13:00:00Z", "duration": 90, "last_ad_at": "2025-10-16T11:00:00Z", "preroll_free_time": 300}]}

---

void snooze_next_ad(broadcaster_id: String) 🔗

Snoozes the next scheduled ad by 5 minutes. Results are returned via the TwitchAPI.request_completed signal with signal_name "ad_snoozed".

Response includes: snooze_count, snooze_refresh_at, next_ad_at.

TwitchAPI.get_ads().snooze_next_ad("broadcaster_id")
# Response: {"data": [{"snooze_count": 0, "snooze_refresh_at": "2025-10-17T00:00:00Z", "next_ad_at": "2025-10-16T13:05:00Z"}]}

---

void start_commercial(broadcaster_id: String, length: int) 🔗

Starts a commercial break on the broadcaster's channel. length must be 30, 60, 90, 120, 150, or 180 seconds. Requires channel:edit:commercial scope. Results are returned via the TwitchAPI.request_completed signal with signal_name "commercial_started".

Response includes: length (commercial duration), message (status message), retry_after (seconds until next commercial can be run).

TwitchAPI.get_ads().start_commercial("broadcaster_id", 30)
# Response: {"data": [{"length": 30, "message": "Commercial started", "retry_after": 480}]}