Streams - API Reference | Twitch Developers

Get Streams

Gets a list of all streams. The list is in descending order by the number of viewers watching the stream. Because viewers come and go during a stream, it's possible to find duplicate or missing streams in the list as you page through the results.

Endpoint

GEThttps://api.twitch.tv/helix/streams

Authorization

Requires one of the following:

A user access token.
An app access token.

Query Parameters

user_idString
A user ID used to filter the list of streams. Returns only the streams of those users that are broadcasting. You may specify a maximum of 100 IDs. To specify multiple IDs, include the user_id parameter for each user. For example, '&user_id=1234&user_id=5678'.
user_loginString
A user login name used to filter the list of streams. Returns only the streams of those users that are broadcasting. You may specify a maximum of 100 login names. To specify multiple names, include the user_login parameter for each user. For example, '&user_login=foo&user_login=bar'.
game_idString
A game (category) ID used to filter the list of streams. Returns only the streams that are broadcasting the game (category). You may specify a maximum of 100 IDs. To specify multiple IDs, include the game_id parameter for each game. For example, '&game_id=9876&game_id=5432'.
typeString
The type of stream to filter the list of streams by. The default is all. Both values return only live streams.
Possible values
- all
- live
languageString
A language code used to filter the list of streams. Returns only streams that broadcast in the specified language. Specify the language using an ISO 639-1 two-letter language code or other if the broadcast uses a language not in the list of supported stream languages.

You may specify a maximum of 100 language codes. To specify multiple languages, include the language parameter for each language. For example, '&language=de&language=fr'.
firstInteger
The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20. If you specify user_id or user_login, the response contains all of the matching streams, regardless of this value.
beforeString
The cursor used to get the previous page of results. The Pagination object in the response contains the cursor's value. Read More
afterString
The cursor used to get the next page of results. The Pagination object in the response contains the cursor's value. Read More

Response Body

dataObject[]
The list of streams. Streams that Twitch restricts from discovery aren't included, except the user's own stream if you use a user access token, so a page may contain fewer than first items even if more pages remain.
Hide child attributesShow child attributes
- data.idString
  An ID that identifies the stream. You can use this ID later to look up the video on demand (VOD).
- data.user_idString
  The ID of the user that's broadcasting the stream.
- data.user_loginString
  The user's login name.
- data.user_nameString
  The user's display name.
- data.game_idString
  The ID of the category or game being streamed. If no category is set on the channel, this will be set to an empty string.
- data.game_nameString
  The name of the category or game being streamed. If no category is set on the channel, this will be set to an empty string.
- data.typeString
  The type of stream.
  Possible values
  - live
- data.titleString
  The stream's title. Is an empty string if not set.
- data.tagsString[]Nullable
  The tags applied to the stream. Is null if the stream has no tags.
- data.viewer_countInteger
  The number of users watching the stream.
- data.started_atString
  The UTC date and time (in RFC3339 format) of when the broadcast began.
- data.languageString
  The language that the stream uses. This is an ISO 639-1 two-letter language code or other if the stream uses a language not in the list of supported stream languages.
- data.thumbnail_urlString
  A URL to an image of a frame from the last 5 minutes of the stream. Replace the width and height placeholders in the URL ('{width}x{height}') with the size of the image you want, in pixels.
- data.tag_idsString[]
  IMPORTANT As of February 28, 2023, this field is deprecated and returns only an empty array. If you use this field, please update your code to use the 'tags' field.
  
  The list of tags that apply to the stream. The list contains IDs only when the channel is steaming live. For a list of possible tags, see List of All Tags. The list doesn't include Category Tags.
- data.is_matureBoolean
  IMPORTANT This field is deprecated and returns only 'false'. A Boolean value that indicates whether the stream is meant for mature audiences.
paginationObject
The information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
Hide child attributesShow child attributes
- pagination.cursorString
  The cursor used to get the next page of results. Set the request's after or before query parameter to this value depending on whether you're paging forwards or backwards.

Response Codes

200OK: Successfully retrieved the list of streams.
400Bad Request: The value in the type query parameter is not valid.
The request may specify the before or after query parameter, but not both.
The cursor specified in the before or after query parameter is not valid.
The first query parameter is outside the allowed range of values.
The request specified too many user_id, user_login, game_id, or language query parameters.
A user_id, user_login, or game_id query parameter contains a comma-separated list. To specify multiple values, repeat the parameter (for example, 'user_id=1234&user_id=5678').
A user_id, user_login, or game_id query parameter contains an empty string.
401Unauthorized: The Authorization header is required and must specify an app access token or user access token.
The access token is not valid.
The ID in the Client-Id header must match the Client ID in the access token.

Request Example

curl -X GET 'https://api.twitch.tv/helix/streams' \
  -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/streams" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/streams", {
  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/streams",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
)

data = response.json()

req, _ := http.NewRequest("GET", "https://api.twitch.tv/helix/streams", 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/streams");

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/streams");
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/streams")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

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

Response Example

{
  "data": [
    {
      "id": "123456789",
      "user_id": "98765",
      "user_login": "sandysanderman",
      "user_name": "SandySanderman",
      "game_id": "494131",
      "game_name": "Little Nightmares",
      "type": "live",
      "title": "hablamos y le damos a Little Nightmares 1",
      "tags": ["Español"],
      "viewer_count": 78365,
      "started_at": "2021-03-10T15:04:21Z",
      "language": "es",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_auronplay-{width}x{height}.jpg",
      "tag_ids": [],
      "is_mature": false
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19"
  }
}

Get Followed Streams

Gets the list of broadcasters that the user follows and that are streaming live.

Endpoint

GEThttps://api.twitch.tv/helix/streams/followed

Authorization

Requires one of the following:

A user access token that includes the user:read:follows scope.

Query Parameters

user_idStringRequired
The ID of the user whose list of followed streams you want to get. This ID must match the user ID in the access token.
firstInteger
The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 100.
afterString
The cursor used to get the next page of results. The Pagination object in the response contains the cursor's value. Read More

Response Body

dataObject[]
The list of live streams of broadcasters that the specified user follows. The list is in descending order by the number of viewers watching the stream. Because viewers come and go during a stream, it's possible to find duplicate or missing streams in the list as you page through the results. The list is empty if none of the followed broadcasters are streaming live. If the user follows more than 2,000 broadcasters, the list includes only streams from the first 2,000 broadcasters that the user followed.
Hide child attributesShow child attributes
- data.idString
  An ID that identifies the stream. You can use this ID later to look up the video on demand (VOD).
- data.user_idString
  The ID of the user that's broadcasting the stream.
- data.user_loginString
  The user's login name.
- data.user_nameString
  The user's display name.
- data.game_idString
  The ID of the category or game being played.
- data.game_nameString
  The name of the category or game being played.
- data.typeString
  The type of stream.
  Possible values
  - live
- data.titleString
  The stream's title. Is an empty string if not set.
- data.viewer_countInteger
  The number of users watching the stream.
- data.started_atString
  The UTC date and time (in RFC3339 format) of when the broadcast began.
- data.languageString
  The language that the stream uses. This is an ISO 639-1 two-letter language code or other if the stream uses a language not in the list of supported stream languages
- data.thumbnail_urlString
  A URL to an image of a frame from the last 5 minutes of the stream. Replace the width and height placeholders in the URL ('{width}x{height}') with the size of the image you want, in pixels.
- data.tag_idsString[]
  IMPORTANT As of February 28, 2023, this field is deprecated and returns only an empty array. If you use this field, please update your code to use the 'tags' field.
  
  The list of tags that apply to the stream. The list contains IDs only when the channel is steaming live. For a list of possible tags, see List of All Tags. The list doesn't include Category Tags.
- data.tagsString[]Nullable
  The tags applied to the stream. Is null if the stream has no tags.
- data.is_matureBoolean
  IMPORTANT This field is deprecated and returns only 'false'. A Boolean value that indicates whether the stream is meant for mature audiences.
paginationObject
The information used to page through the list of results. The object is empty if the page contains fewer streams than the page size (see first). A full page includes a cursor even if no more streams remain, in which case the next page is empty. Read More
Hide child attributesShow child attributes
- pagination.cursorString
  The cursor used to get the next page of results. Set the request's after query parameter to this value.

Response Codes

200OK: Successfully retrieved the list of broadcasters that the user follows and that are streaming live.
400Bad Request: The user_id query parameter is required.
The first query parameter is outside the allowed range of values.
The cursor specified in the after query parameter is not valid.
401Unauthorized: The ID in user_id must match the user ID found in the access token.
The Authorization header is required and must contain a user access token.
The user access token must include the user:read:follows 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 access token.

Request Example

curl -X GET 'https://api.twitch.tv/helix/streams/followed?user_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/streams/followed?user_id=141981764" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/streams/followed?user_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/streams/followed",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    params={
        "user_id": "141981764",
    },
)

data = response.json()

req, _ := http.NewRequest("GET", "https://api.twitch.tv/helix/streams/followed?user_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/streams/followed?user_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/streams/followed?user_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/streams/followed?user_id=141981764")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

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

Response Example

{
  "data": [
    {
      "id": "42170724654",
      "user_id": "132954738",
      "user_login": "aws",
      "user_name": "AWS",
      "game_id": "417752",
      "game_name": "Talk Shows & Podcasts",
      "type": "live",
      "title": "AWS Howdy Partner! Y'all welcome ExtraHop to the show!",
      "viewer_count": 20,
      "started_at": "2021-03-31T20:57:26Z",
      "language": "en",
      "thumbnail_url": "https://static-cdn.jtvnw.net/previews-ttv/live_user_aws-{width}x{height}.jpg",
      "tag_ids": [],
      "tags": ["English"]
    },
    ...
  ],
  "pagination": {
    "cursor": "eyJiIjp7IkN1cnNvciI6ImV5SnpJam8zT0RNMk5TNDBORFF4TlRjMU1UY3hOU3dpWkNJNlptRnNjMlVzSW5RaU9uUnlkV1Y5In0sImEiOnsiQ3Vyc29yIjoiZXlKeklqb3hOVGs0TkM0MU56RXhNekExTVRZNU1ESXNJbVFpT21aaGJITmxMQ0owSWpwMGNuVmxmUT09In19"
  }
}

Get Stream Key

Gets the channel's stream key.

Endpoint

GEThttps://api.twitch.tv/helix/streams/key

Authorization

Requires one of the following:

A user access token that includes the channel:read:stream_key scope.

Query Parameters

broadcaster_idStringRequired
The ID of the broadcaster that owns the channel. The ID must match the user ID in the access token.

Response Body

dataObject[]
A list that contains the channel's stream key.
Hide child attributesShow child attributes
- data.stream_keyString
  The channel's stream key.

Response Codes

200OK: Successfully retrieved the stream's key.
400Bad Request: The broadcaster_id field is required.
401Unauthorized: The ID in broadcaster_id must match the user ID in the access token.
The Authorization header is required and must contain a user access token.
The user access token must include the channel:read:stream_key scope.
The access token is not valid.
The client ID specified in the Client-Id header must match the client ID specified in the access token.
403Forbidden: The user must complete additional steps in order to stream. Present the user with the returned error message.
The user is not permitted to get a stream key.

Request Example

curl -X GET 'https://api.twitch.tv/helix/streams/key?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/streams/key?broadcaster_id=141981764" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/streams/key?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/streams/key",
    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/streams/key?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/streams/key?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/streams/key?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/streams/key?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": [
    {
      "stream_key": "live_44322889_a34ub37c8ajv98a0"
    }
  ]
}

Get Stream Markers

Gets a list of markers from the user's most recent stream or from the specified VOD/video. A marker is an arbitrary point in a live stream that the broadcaster or editor marked, so they can return to that spot later to create video highlights. For more information on these features, see Creating Highlights and Stream Markers.

You must specify exactly one of the user_id and video_id query parameters; the request fails if you specify none of them or more than one.

Endpoint

GEThttps://api.twitch.tv/helix/streams/markers

Authorization

Requires one of the following:

A user access token that includes the user:read:broadcast or channel:manage:broadcast scope.

Query Parameters

user_idString
A user ID. The request returns the markers from this user's most recent past broadcast (a video of type archive); highlights and uploads aren't considered. This ID must match the user ID in the access token or the user in the access token must be one of the broadcaster's editors.

This parameter and the video_id query parameter are mutually exclusive.
video_idString
A video on demand (VOD)/video ID. The request returns the markers from this VOD/video. The user in the access token must own the video or the user must be one of the broadcaster's editors.

This parameter and the user_id query parameter are mutually exclusive.
firstInteger
The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100 items per page. The default is 20.
afterString
The cursor used to get the next page of results. The Pagination object in the response contains the cursor's value. Read More

Response Body

dataObject[]
The list of markers grouped by the user that created the marks.
Hide child attributesShow child attributes
- data.user_idString
  The ID of the user that created the marker.
- data.user_nameString
  The user's display name.
- data.user_loginString
  The user's login name.
- data.videosObject[]
  A list of videos that contain markers. The list contains a single video.
  Hide child attributesShow child attributes
  - data.videos.video_idString
    An ID that identifies this video.
  - data.videos.markersObject[]
    The list of markers in this video. The list is in ascending order by the marker's position in the video (see position_seconds).
    Hide child attributesShow child attributes
    data.videos.markers.idString
    An ID that identifies this marker.
    data.videos.markers.created_atString
    The UTC date and time (in RFC3339 format) of when the user created the marker.
    data.videos.markers.descriptionString
    The description that the user gave the marker to help them remember why they marked the location. Is an empty string if the user didn't provide one.
    data.videos.markers.position_secondsInteger
    The relative offset (in seconds) of the marker from the beginning of the stream.
    data.videos.markers.URLString
    A URL that opens the video in Twitch Highlighter.
paginationObject
The information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
Hide child attributesShow child attributes
- pagination.cursorString
  The cursor used to get the next page of results. Set the request's after query parameter to this value.

Response Codes

200OK: Successfully retrieved the list of markers.
400Bad Request: The request must specify either the user_id or video_id query parameter, but not both.
The ID in the video_id query parameter is not valid.
401Unauthorized: The Authorization header is required and must contain a user access token.
The user access token must include the user:read:broadcast or channel:manage:broadcast 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.
403Forbidden: The user in the access token is not authorized to get the video's markers. The user in the access token must own the video or be one of the broadcaster's editors.
404Not Found: The user specified in the user_id query parameter doesn't have any past broadcasts.
The video specified in the video_id query parameter was not found.

Request Example

curl -X GET 'https://api.twitch.tv/helix/streams/markers?user_id=123&first=5' \
  -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/streams/markers?user_id=123&first=5" `
    -Method Get -Headers $headers

const response = await fetch("https://api.twitch.tv/helix/streams/markers?user_id=123&first=5", {
  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/streams/markers",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    params={
        "user_id": "123",
        "first": "5",
    },
)

data = response.json()

req, _ := http.NewRequest("GET", "https://api.twitch.tv/helix/streams/markers?user_id=123&first=5", 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/streams/markers?user_id=123&first=5");

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/streams/markers?user_id=123&first=5");
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/streams/markers?user_id=123&first=5")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .send()
    .await?;

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

Response Example

{
  "data": [
    {
      "user_id": "123",
      "user_name": "TwitchName",
      "user_login": "twitchname",
      "videos": [
        {
          "video_id": "456",
          "markers": [
            {
              "id": "106b8d6243a4f883d25ad75e6cdffdc4",
              "created_at": "2018-08-20T20:10:03Z",
              "description": "hello, this is a marker!",
              "position_seconds": 244,
              "URL": "https://twitch.tv/twitchname/manager/highlighter/456?t=0h4m06s"
            },
            ...
          ]
        }
      ]
    }
  ],
  "pagination": {
    "cursor": "eyJiIjpudWxsLCJhIjoiMjk1MjA0Mzk3OjI1Mzpib29rbWFyazoxMDZiOGQ1Y"
  }
}

Create Stream Marker

Adds a marker to a live stream.

A marker is an arbitrary point in a live stream that the broadcaster or editor wants to mark, so they can return to that spot later to create video highlights. For more information on these features, see Creating Highlights and Stream Markers.

You may not add markers:

If the stream is not live.
If the stream has not enabled video on demand (VOD).
If the stream is a rerun of a past broadcast.
If the stream is a premiere.

Endpoint

POSThttps://api.twitch.tv/helix/streams/markers

Authorization

Requires one of the following:

A user access token that includes the channel:manage:broadcast or user:edit:broadcast scope.

Request Body

user_idStringRequired
The ID of the broadcaster that's streaming content. This ID must match the user ID in the access token or the user in the access token must be one of the broadcaster's editors.
descriptionString
A short description of the marker to help the user remember why they marked the location. The maximum length of the description is 140 characters.

Response Body

dataObject[]
A list that contains the single marker that you added.
Hide child attributesShow child attributes
- data.idString
  An ID that identifies this marker.
- data.created_atString
  The UTC date and time (in RFC3339 format) of when the user created the marker.
- data.position_secondsInteger
  The relative offset (in seconds) of the marker from the beginning of the stream.
- data.descriptionString
  A description that the user gave the marker to help them remember why they marked the location.

Response Codes

200OK: Successfully created the marker.
400Bad Request: The user_id field is required.
The length of the string in the 'description' field is too long.
The broadcaster is streaming a rerun or a premiere.
401Unauthorized: The Authorization header is required and must contain a user access token.
The user access token must include the channel:manage:broadcast or user:edit:broadcast 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.
403Forbidden: The user in the access token is not authorized to create video markers for the user in the user_id field. The user in the access token must own the video or they must be one of the broadcaster's editors.
404Not Found: The user in the user_id field is not streaming live.
The ID in the user_id field is not valid.
The user hasn't enabled video on demand (VOD).
Markers aren't available during the first few seconds of a stream. Wait a few seconds and try again.

Request Example

curl -X POST 'https://api.twitch.tv/helix/streams/markers' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID' \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"123","description":"hello, this is a marker!"}'

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

$body = '{"user_id":"123","description":"hello, this is a marker!"}'

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

const response = await fetch("https://api.twitch.tv/helix/streams/markers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Client-Id": "YOUR_CLIENT_ID",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "user_id": "123",
    "description": "hello, this is a marker!"
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.twitch.tv/helix/streams/markers",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Client-Id": "YOUR_CLIENT_ID",
    },
    json={
        "user_id": "123",
        "description": "hello, this is a marker!",
    },
)

data = response.json()

body := strings.NewReader(`{"user_id":"123","description":"hello, this is a marker!"}`)

req, _ := http.NewRequest("POST", "https://api.twitch.tv/helix/streams/markers", 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/streams/markers");

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, '{"user_id":"123","description":"hello, this is a marker!"}');

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

using var client = new HttpClient();

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

request.Content = new StringContent("{\"user_id\":\"123\",\"description\":\"hello, this is a marker!\"}",
    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/streams/markers")
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Client-Id", "YOUR_CLIENT_ID")
    .json(&serde_json::json!({
        "user_id": "123",
        "description": "hello, this is a marker!"
    }))
    .send()
    .await?;

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

Response Example

{
  "data": [
    {
      "id": "123",
      "created_at": "2018-08-20T20:10:03Z",
      "description": "hello, this is a marker!",
      "position_seconds": 244
    }
  ]
}