Go Live

POST

broadcasts

Go Live on a Source

curl --request POST \
  --url https://api.x.com/2/broadcasts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source_id": "<string>",
  "additional_source_ids": [
    "<string>"
  ],
  "chat_option": 3,
  "live_category_id": "<string>",
  "locale": "<string>",
  "should_not_tweet": true,
  "title": "<string>"
}
'

import requests

url = "https://api.x.com/2/broadcasts"

payload = {
    "source_id": "<string>",
    "additional_source_ids": ["<string>"],
    "chat_option": 3,
    "live_category_id": "<string>",
    "locale": "<string>",
    "should_not_tweet": True,
    "title": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    source_id: '<string>',
    additional_source_ids: ['<string>'],
    chat_option: 3,
    live_category_id: '<string>',
    locale: '<string>',
    should_not_tweet: true,
    title: '<string>'
  })
};

fetch('https://api.x.com/2/broadcasts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.x.com/2/broadcasts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'source_id' => '<string>',
    'additional_source_ids' => [
        '<string>'
    ],
    'chat_option' => 3,
    'live_category_id' => '<string>',
    'locale' => '<string>',
    'should_not_tweet' => true,
    'title' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.com/2/broadcasts"

	payload := strings.NewReader("{\n  \"source_id\": \"<string>\",\n  \"additional_source_ids\": [\n    \"<string>\"\n  ],\n  \"chat_option\": 3,\n  \"live_category_id\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"should_not_tweet\": true,\n  \"title\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.x.com/2/broadcasts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"source_id\": \"<string>\",\n  \"additional_source_ids\": [\n    \"<string>\"\n  ],\n  \"chat_option\": 3,\n  \"live_category_id\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"should_not_tweet\": true,\n  \"title\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.x.com/2/broadcasts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"source_id\": \"<string>\",\n  \"additional_source_ids\": [\n    \"<string>\"\n  ],\n  \"chat_option\": 3,\n  \"live_category_id\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"should_not_tweet\": true,\n  \"title\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "broadcast_id": "<string>",
    "id": "<string>",
    "share_url": "<string>",
    "state": "<string>",
    "chat_option": 123,
    "language": "<string>",
    "live_category_id": "<string>",
    "media_key": "<string>",
    "start_ms": "<string>",
    "title": "<string>",
    "tweet_id": "<string>"
  },
  "errors": [
    {
      "detail": "<string>",
      "resource_type": "<string>",
      "title": "<string>",
      "type": "https://api.x.com/2/problems/resource-not-found",
      "parameter": "<string>",
      "resource_id": "<string>",
      "status": 123,
      "value": "<string>"
    }
  ]
}

{
  "code": 123,
  "message": "<string>"
}

Takes one of the authenticated user’s sources live in one call. The broadcast is created and published together: it is RUNNING and publicly visible as soon as the request succeeds. This route replaces the deprecated Create Broadcast + Publish sequence; see the migration guide. The broadcast goes live immediately, even before your encoder sends video. If no video arrives within 5 minutes, the broadcast is ended with state TIMED_OUT. Start your encoder right before or right after this call. By default, the broadcast is announced in a Post from the authenticated user. Set should_not_tweet: true to skip the Post.

Request body

source_id is required. It is the source id (19 digits) of one of your sources, from Get Sources or Create a Source. It is not the stream key: passing a stream key returns 400 with The `source_id` value is not a source id. The body is strictly typed: chat_option must be a JSON integer from 0 to 6 and should_not_tweet a JSON boolean (strings such as "2" or "true" are rejected). Fields other than source_id, title, locale, chat_option and should_not_tweet, such as region or is_low_latency, are rejected with 400.

Chat option values

Value	Meaning
`0`	Default (no option set)
`1`	Chat disabled
`2`	Everyone
`3`	Verified accounts
`4`	Accounts the broadcaster follows
`5`	The broadcaster’s subscribers
`6`	Accounts followed by an account the broadcaster follows

Responses

201 Created: the source went live. data is the new broadcast, with state RUNNING.
200 OK: the source already had a live broadcast. data is that broadcast, returned unchanged: the request’s title, locale, chat_option and should_not_tweet are ignored.

Both have the same shape. id (also returned as broadcast_id) is the broadcast ID to use in the other /2/broadcasts routes; IDs vary in length, so don’t assume a fixed length. share_url is the public viewer link. Fields without a value are omitted. The response doesn’t include the source’s stream key. Fetch the full broadcast, including viewer counts, thumbnails and source_id, with GET /2/broadcasts/:id.

Announcing Post

tweet_id is the ID of the Post announcing the broadcast. It is missing when the Post hasn’t been created yet, when you set should_not_tweet: true, or when the Post couldn’t be created. To read it later, call GET /2/broadcasts/:id a moment after going live. If it’s still missing, the Post wasn’t created. The broadcast is live either way, and viewers can watch it at share_url. Don’t retry the request to get a Post: a retry returns the same live broadcast with 200 and doesn’t post again. Share share_url yourself if you need an announcement.

Errors

Errors use the standard X API problem format. The problem type identifies the error:

Status	Problem `type`	When	What to do
`400`	`https://api.x.com/2/problems/invalid-request`	The body is invalid: a missing `source_id`, a `chat_option` outside `0`–`6`, a wrongly typed value or an unknown field. The message for each invalid field is in the problem’s `errors` array.	Fix the request body.
`400`	`https://api.x.com/2/problems/invalid-request`	The `source_id` value is not a source id. You sent a stream key or another value that isn’t a source id. The value isn’t echoed back.	Pass the source’s `id` from Get Sources.
`401`	`about:blank`	The request isn’t authenticated.	Send a valid user-context access token.
`403`	`about:blank`	The account isn’t eligible to go live, or the broadcast was moderated.	Don’t retry.
`403`	`https://api.x.com/2/problems/missing-scopes`	The OAuth 2.0 token lacks `broadcast.write`.	Re-authorize the user with the `broadcast.read` and `broadcast.write` scopes.
`404`	`https://api.x.com/2/problems/resource-not-found`	The source doesn’t exist or belongs to another user.	Check `source_id`.
`409`	`https://api.x.com/2/problems/conflict`	The source can’t take video before its encoder connects (for example, some regions and external HLS sources).	Start your encoder, wait until `is_stream_active` is `true` on Get Source by ID, then retry.
`409`	`https://api.x.com/2/problems/conflict`	Another broadcast is live on the source. The `detail` names that broadcast when known.	End that broadcast first, then retry, or use a different source.
`503`	`about:blank`	Temporary failure.	Retry with backoff.

Retries

Go Live is safe to retry. If an earlier request already took the source live (for example, the response was lost to a timeout), a retry returns 200 with that broadcast instead of creating a second one. On a 503, or a 409 because the encoder hasn’t connected, retry with backoff. A 409 for another broadcast live on the source doesn’t clear on its own; end that broadcast first.

Next steps

While live, poll GET /2/broadcasts/:id for state, viewer counts and tweet_id.
When done, stop your encoder and end the broadcast.

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Scopes

broadcast.read

View your live broadcasts and their chat.

broadcast.write

Manage your live broadcasts and send chat messages on your behalf.

Body

application/json

source_id

string

required

Id of the source to go live on: a source's id (19 digits) from GET /2/sources.

additional_source_ids

string[]

Ids of further sources to go live on together with source_id, one per video format, at most 2, each a source's id from GET /2/sources. source_id comes first; duplicates are ignored.

Required array length: 1 - 2 elements

chat_option

integer

Who can chat: 0 default, 1 chat off, 2 everyone, 3 verified accounts, 4 accounts the host follows, 5 the host's subscribers, 6 accounts followed by an account the host follows.

Required range: 0 <= x <= 6

live_category_id

string

The live category the host picked, e.g. gaming. Ids come from GET /2/broadcasts/categories; an unknown id is a 400. Ignored when the source already has a live broadcast.

Maximum string length: 64

locale

string

Broadcast language, e.g. en.

should_not_tweet

boolean

Skip the Post announcing the broadcast. Defaults to false.

title

string

Broadcast title. Defaults to the user's display name.

Response

The request has succeeded.

data

object

Show child attributes

errors

object[]

Show child attributes

Go Live on a Source

curl --request POST \
  --url https://api.x.com/2/broadcasts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source_id": "<string>",
  "additional_source_ids": [
    "<string>"
  ],
  "chat_option": 3,
  "live_category_id": "<string>",
  "locale": "<string>",
  "should_not_tweet": true,
  "title": "<string>"
}
'

import requests

url = "https://api.x.com/2/broadcasts"

payload = {
    "source_id": "<string>",
    "additional_source_ids": ["<string>"],
    "chat_option": 3,
    "live_category_id": "<string>",
    "locale": "<string>",
    "should_not_tweet": True,
    "title": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    source_id: '<string>',
    additional_source_ids: ['<string>'],
    chat_option: 3,
    live_category_id: '<string>',
    locale: '<string>',
    should_not_tweet: true,
    title: '<string>'
  })
};

fetch('https://api.x.com/2/broadcasts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.x.com/2/broadcasts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'source_id' => '<string>',
    'additional_source_ids' => [
        '<string>'
    ],
    'chat_option' => 3,
    'live_category_id' => '<string>',
    'locale' => '<string>',
    'should_not_tweet' => true,
    'title' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.com/2/broadcasts"

	payload := strings.NewReader("{\n  \"source_id\": \"<string>\",\n  \"additional_source_ids\": [\n    \"<string>\"\n  ],\n  \"chat_option\": 3,\n  \"live_category_id\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"should_not_tweet\": true,\n  \"title\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.x.com/2/broadcasts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"source_id\": \"<string>\",\n  \"additional_source_ids\": [\n    \"<string>\"\n  ],\n  \"chat_option\": 3,\n  \"live_category_id\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"should_not_tweet\": true,\n  \"title\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.x.com/2/broadcasts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"source_id\": \"<string>\",\n  \"additional_source_ids\": [\n    \"<string>\"\n  ],\n  \"chat_option\": 3,\n  \"live_category_id\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"should_not_tweet\": true,\n  \"title\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "broadcast_id": "<string>",
    "id": "<string>",
    "share_url": "<string>",
    "state": "<string>",
    "chat_option": 123,
    "language": "<string>",
    "live_category_id": "<string>",
    "media_key": "<string>",
    "start_ms": "<string>",
    "title": "<string>",
    "tweet_id": "<string>"
  },
  "errors": [
    {
      "detail": "<string>",
      "resource_type": "<string>",
      "title": "<string>",
      "type": "https://api.x.com/2/problems/resource-not-found",
      "parameter": "<string>",
      "resource_id": "<string>",
      "status": 123,
      "value": "<string>"
    }
  ]
}

{
  "code": 123,
  "message": "<string>"
}

Overview

Stream Sources

Broadcasts

Scheduled Broadcasts

Live Chat

Go Live

Request body

Chat option values

Responses

Announcing Post

Errors

Retries

Next steps

Authorizations

Scopes

Body

Response