Ads - API Reference | Twitch Developers

Get Ad Schedule

Returns ad schedule related information, including snooze, when the last ad was run, when the next ad is scheduled, and if the channel is currently in pre-roll free time.

Note

After an ad starts, a new ad cannot be run until the cooldown period ends. The cooldown is 8 minutes by default and is never shorter than the ad.

Endpoint

GEThttps://api.twitch.tv/helix/channels/ads

Authorization

Requires one of the following:

A user access token that includes the channel:read:ads scope.The User ID associated with the token must match the broadcaster_id in the query parameter.
An app access token.The application, through prior authorization, must have been granted:
- The channel:read:ads scope for the user represented by the broadcaster_id query parameter.

Query Parameters

broadcaster_idStringRequired
Provided broadcaster_id must match the user_id in the authentication token.

Response Body

dataObject[]
A list that contains information related to the channel's ad schedule.
Hide child attributesShow child attributes
- data.snooze_countInteger
  The number of snoozes available for the broadcaster.
- data.snooze_refresh_atInteger
  The time when the broadcaster will gain an additional snooze, as a Unix timestamp in seconds. Is 0 if the broadcaster already has the maximum number of snoozes.
- data.next_ad_atInteger
  The time of the broadcaster's next scheduled ad, as a Unix timestamp in seconds. Is 0 if the channel has no ad scheduled or is not live.
- data.durationInteger
  The length in seconds of the scheduled upcoming ad break.
- data.last_ad_atInteger
  The time of the broadcaster's last ad-break, as a Unix timestamp in seconds. Is 0 if the channel has not run an ad or is not live.
- data.preroll_free_timeInteger
  The amount of pre-roll free time remaining for the channel in seconds. Returns 0 if they are currently not pre-roll free.

Response Codes

200OK: Returns the ad schedule information for the channel.
400Bad Request: The broadcaster ID is not valid.
401Unauthorized: The ID in broadcaster_id must match the user ID in the user access token.
The Authorization header is required and must contain a user access token or an app access token.
The user access token must include the channel:read:ads scope.
If you use an app access token, the user in broadcaster_id must have authorized your app with the channel:read:ads scope.
The access token is not valid.
The client ID specified in the Client-Id header does not match the client ID specified in the access token.
404Not Found: The ID in broadcaster_id was not found.
500Internal Server Error: An internal server error occurred. Please report this issue on our issue tracker.

Request Example

curl -X GET 'https://api.twitch.tv/helix/channels/ads?broadcaster_id=141981764' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/channels/ads?broadcaster_id=141981764" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/channels/ads?broadcaster_id=141981764", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
  },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.twitch.tv/helix/channels/ads",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    params={
        "broadcaster_id": "141981764",
    },
)

data = response.json()

req, _ := http.NewRequest("GET", "https://api.twitch.tv/helix/channels/ads?broadcaster_id=141981764", nil)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/channels/ads?broadcaster_id=141981764");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
]);

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.twitch.tv/helix/channels/ads?broadcaster_id=141981764");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .get("https://api.twitch.tv/helix/channels/ads?broadcaster_id=141981764")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

let data = response.text().await?;

Response Example

{
  "data": [
    {
      "next_ad_at": 1690931298,
      "last_ad_at": 1690930398,
      "duration": 60,
      "preroll_free_time": 90,
      "snooze_count": 1,
      "snooze_refresh_at": 1690932198
    }
  ]
}

Snooze Next Ad

If available, pushes back the timestamp of the upcoming automatic mid-roll ad by 5 minutes. This endpoint duplicates the snooze functionality in the creator dashboard's Ads Manager.

Endpoint

POSThttps://api.twitch.tv/helix/channels/ads/schedule/snooze

Authorization

Requires one of the following:

A user access token that includes the channel:manage:ads scope.The user ID associated with the token must match the broadcaster_id in the query parameter.
An app access token.The application, through prior authorization, must have been granted:
- The channel:manage:ads scope for the user represented by the broadcaster_id query parameter.

Query Parameters

broadcaster_idStringRequired
Provided broadcaster_id must match the user_id in the authentication token.

Response Body

dataObject[]
A list that contains information about the channel's snoozes and next upcoming ad after successfully snoozing.
Hide child attributesShow child attributes
- data.snooze_countInteger
  The number of snoozes available for the broadcaster.
- data.snooze_refresh_atInteger
  The time when the broadcaster will gain an additional snooze, as a Unix timestamp in seconds.
- data.next_ad_atInteger
  The time of the broadcaster's next scheduled ad, as a Unix timestamp in seconds.

Response Codes

200OK: User's next ad is successfully snoozed. Their snooze_count is decremented and snooze_refresh_at and next_ad_at are both updated.
400Bad Request: The channel is not currently live.
The broadcaster ID is not valid.
Channel does not have an upcoming scheduled ad break.
401Unauthorized: The ID in broadcaster_id must match the user ID in the user access token.
The Authorization header is required and must contain a user access token or an app access token.
The user access token must include the channel:manage:ads scope.
If you use an app access token, the user in broadcaster_id must have authorized your app with the channel:manage:ads scope.
The access token is not valid.
The client ID specified in the Client-Id header does not match the client ID specified in the access token.
404Not Found: The ID in broadcaster_id was not found.
429Too Many Requests: Channel has no snoozes left.
Another ad or snooze request for the channel is in progress. Try again shortly.
500Internal Server Error: An internal server error occurred. Please report this issue on our issue tracker.

Request Example

curl -X POST 'https://api.twitch.tv/helix/channels/ads/schedule/snooze?broadcaster_id=123' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/channels/ads/schedule/snooze?broadcaster_id=123" `
    -Method Post -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/channels/ads/schedule/snooze?broadcaster_id=123", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
  },
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.twitch.tv/helix/channels/ads/schedule/snooze",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    params={
        "broadcaster_id": "123",
    },
)

data = response.json()

req, _ := http.NewRequest("POST", "https://api.twitch.tv/helix/channels/ads/schedule/snooze?broadcaster_id=123", nil)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/channels/ads/schedule/snooze?broadcaster_id=123");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
]);

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.twitch.tv/helix/channels/ads/schedule/snooze?broadcaster_id=123");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .post("https://api.twitch.tv/helix/channels/ads/schedule/snooze?broadcaster_id=123")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

let data = response.text().await?;

Response Example

{
  "data": [
    {
      "snooze_count": 1,
      "snooze_refresh_at": 1690932198,
      "next_ad_at": 1690931298
    }
  ]
}

Start Commercial

Starts a commercial on the specified channel.

Note

Only partners and affiliates may run commercials and they must be streaming live at the time.

Note

Only the broadcaster may start a commercial; the broadcaster's editors and moderators may not start commercials on behalf of the broadcaster.

Endpoint

POSThttps://api.twitch.tv/helix/channels/commercial

Authorization

Requires one of the following:

A user access token that includes the channel:edit:commercial scope.
An app access token.The application, through prior authorization, must have been granted:
- The channel:edit:commercial scope for the user represented by the broadcaster_id body field.

Request Body

broadcaster_idStringRequired
The ID of the partner or affiliate broadcaster that wants to run the commercial. This ID must match the user ID found in the OAuth token.
lengthIntegerRequired
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. If you request a commercial that's longer than the channel's maximum ad break length, the API uses the maximum. For most channels, the maximum is 180 seconds.

Response Body

dataObject[]
An array that contains a single object with the status of your start commercial request.
Hide child attributesShow child attributes
- data.lengthInteger
  The length of the commercial, in seconds. If you requested a commercial that's longer than the channel's maximum ad break length, this is the maximum length.
- data.messageString
  A message that indicates whether Twitch was able to serve an ad.
- data.retry_afterInteger
  The number of seconds you must wait before running another commercial.

Response Codes

200OK: Successfully started the commercial.
400Bad Request: The broadcaster_id query parameter is required.
The length query parameter is required.
The ID in broadcaster_id is not valid.
To start a commercial, the broadcaster must be streaming live.
401Unauthorized: The ID in broadcaster_id must match the user ID found in the request's OAuth token.
The Authorization header is required and must contain a user access token or an app access token.
The user access token must include the channel:edit:commercial scope.
If you use an app access token, the user in broadcaster_id must have authorized your app with the channel:edit:commercial scope.
The OAuth token is not valid.
The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
404Not Found: The ID in broadcaster_id was not found.
429Too Many Requests: The broadcaster may not run another commercial until the cooldown period expires. The retry_after field in the previous start commercial response specifies the amount of time the broadcaster must wait between running commercials.
Another ad or snooze request for the channel is in progress. Try again shortly.

Request Example

curl -X POST 'https://api.twitch.tv/helix/channels/commercial' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID' \
  -H 'Content-Type: application/json' \
  -d '{"broadcaster_id":"141981764","length":60}'

$headers = @{
    "Authorization" = "Bearer YOUR_ACCESS_TOKEN"
    "Client-Id"     = "YOUR_CLIENT_ID"
}

$body = '{"broadcaster_id":"141981764","length":60}'

$response = Invoke-RestMethod -Uri "https://api.twitch.tv/helix/channels/commercial" `
    -Method Post -Headers $headers `
    -ContentType "application/json" -Body $body

const response = await fetch("https://api.twitch.tv/helix/channels/commercial", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "broadcaster_id": "141981764",
    "length": 60
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.twitch.tv/helix/channels/commercial",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    json={
        "broadcaster_id": "141981764",
        "length": 60,
    },
)

data = response.json()

body := strings.NewReader(`{"broadcaster_id":"141981764","length":60}`)

req, _ := http.NewRequest("POST", "https://api.twitch.tv/helix/channels/commercial", body)
req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
req.Header.Set("Client-Id", "YOUR_CLIENT_ID")
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

data, _ := io.ReadAll(res.Body)

$ch = curl_init("https://api.twitch.tv/helix/channels/commercial");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Client-Id: YOUR_CLIENT_ID",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"broadcaster_id":"141981764","length":60}');

$response = curl_exec($ch);
curl_close($ch);

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.twitch.tv/helix/channels/commercial");
request.Headers.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
request.Headers.Add("Client-Id", "YOUR_CLIENT_ID");

request.Content = new StringContent("{\"broadcaster_id\":\"141981764\",\"length\":60}",
    Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
var data = await response.Content.ReadAsStringAsync();

let client = reqwest::Client::new();

let response = client
    .post("https://api.twitch.tv/helix/channels/commercial")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .json(&serde_json::json!({
        "broadcaster_id": "141981764",
        "length": 60
    }))
    .send()
    .await?;

let data = response.text().await?;

Response Example

{
  "data": [
    {
      "length": 60,
      "message": "Starting commercial break. Keep in mind you are still live and not all viewers will receive a commercial.",
      "retry_after": 480
    }
  ]
}