Broadcasts
Go Live
POST /2/broadcasts takes one of your stream sources live in one call and returns the new broadcast, already RUNNING.
POST
/
2
/
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, should_not_tweet and live_category_id, 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 |
Live category
live_category_id is optional. It sets the live category the host picked for the broadcast, for example gaming. Get the valid ids from Get Live Categories (GET /2/broadcasts/categories). An id that isn’t in that list returns 400. Leave the field out to go live without a category.
The category can only be set when going live.
Responses
201 Created: the source went live.datais the new broadcast, with stateRUNNING.200 OK: the source already had a live broadcast.datais that broadcast, returned unchanged: the request’stitle,locale,chat_option,should_not_tweetandlive_category_idare ignored.
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. live_category_id is the broadcast’s live category, when it has one. 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 problemtype 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. |
400 | https://api.x.com/2/problems/invalid-request | `live_category_id` is not a live category id. The id isn’t in the list of live categories. The value isn’t echoed back. | Pass an id from Get Live Categories, or leave the field out. |
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 returns200 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/:idfor state, viewer counts andtweet_id. - When done, stop your encoder and end the broadcast.
Authorizations
OAuth2UserTokenUserToken
Scopes
Body
application/json
Response
The request has succeeded.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
- Option 12
- Option 13
- Option 14
- Option 15
- Option 16
- Option 17
- Option 18
- Option 19
- Option 20
- Option 21
- Option 22
- Option 23
- Option 24
- Option 25
- Option 26
- Option 27
- Option 28
- Option 29
- Option 30
- Option 31
- Option 32
- Option 33
- Option 34
- Option 35
- Option 36
- Option 37
- Option 38
- Option 39
- Option 40
- Option 41
- Option 42
- Option 43
- Option 44
- Option 45
- Option 46
- Option 47
- Option 48
- Option 49
- Option 50
- Option 51
- Option 52
- Option 53
- Option 54
- Option 55
- Option 56
- Option 57
- Option 58
- Option 59
- Option 60
- Option 61
Show child attributes
Show child attributes
⌘I
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>"
}