Skip to main content
POST
Go Live on a Source
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

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:

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

Authorizations

Authorization
string
header
required

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

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.

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
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
errors
object[]