Broadcast Lifecycle

Broadcasts are ephemeral live sessions tied to a stream source, moving through NOT_STARTED, RUNNING, and ENDED states.

Broadcasts are ephemeral sessions tied to a source. Go Live (POST /2/broadcasts) creates a broadcast that is already RUNNING. With the deprecated create-then-publish routes, a broadcast starts in NOT_STARTED and moves to RUNNING when published. Either way, it ends in ENDED (or another terminal state).

Broadcast states

State	Meaning
NOT_STARTED	Created but not yet live. Initial state returned by the deprecated Create Broadcast.
PRE_PUBLISHED	Transitional state while the broadcast is being prepared to go live.
RUNNING	Live and publicly visible. Returned by Go Live, or set after a successful PUBLISH.
ENDED	Finished normally after END. Terminal — a broadcast cannot be restarted.
TIMED_OUT	Terminal. The broadcast was not published in time, or ingest stopped before it went live. A broadcast started with Go Live is also ended with TIMED_OUT if no video arrives within 5 minutes.
CANCELED	Terminal. The broadcast was canceled before or during its lifecycle.

The only transitions you trigger directly are going live (Go Live, or NOT_STARTED → RUNNING via the deprecated PUBLISH) and RUNNING → ENDED (via END). The remaining states are set by the platform.

Usually, a source doesn’t need to be receiving video to go live. Go Live makes the broadcast RUNNING right away, and video appears once your encoder is sending to the source; if no video arrives within 5 minutes, the broadcast ends as TIMED_OUT. Some sources can’t take video before their encoder connects, and Go Live returns 409 for them until it does. Starting your encoder first avoids this.

A broadcast created with the deprecated Create Broadcast route but never published isn’t listed and is deleted after 7 days.

Eligibility

The broadcasting account must be allowed to go live on X. For accounts that aren’t, Go Live returns 403 (“This account is not eligible to go live.”). On the deprecated routes, List Broadcasts returns 412 (“Listing broadcasts requires X Premium or more than 1,000 followers.”) and Create Broadcast returns 412 (“This account can’t create broadcasts.”), both with error_type: "preconditionFailed".

Broadcast object

Field	Description
id, broadcast_id	Broadcast ID (the same value).
media_key, media_id	Media identifiers, used for chat access.
state	See Broadcast states.
status	Broadcast title.
twitter_user_id	Numeric X user ID of the broadcaster, as a string.
created_at_ms, updated_at_ms, start_ms, end_ms	Timestamps in milliseconds since the Unix epoch, as strings. start_ms and end_ms appear once the broadcast has gone live or ended.
chat_option	Who can chat; see chat option values.
language	Broadcast language, when a locale was sent at publish.
height, width	Video dimensions in pixels.
available_for_replay	Whether a replay is available.
is_high_latency	Informational latency flag.
image_url, image_url_medium, image_url_small	Thumbnails. A placeholder image until video arrives.
total_watching, total_watched	Live and cumulative viewer counts, as strings.
tweet_id	The announcement post, once it exists.

On the /2/broadcasts routes, the title is returned as title instead of status, the broadcast also includes share_url and source_id, and media_id isn’t returned. source_id is the source id of the broadcast’s stream source, as returned by Get Sources; request it with broadcast.fields=source_id. It is omitted when the source has been deleted. See the migration guide.

Broadcast objects no longer include user_id, username, twitter_username, user_display_name, profile_image_url, has_location, lat, lng, friend_chat, private_chat, is_locked, has_moderation, no_hearts, camera_rotation, ping_ms, version, broadcast_source or unavailable_in_periscope. Use GET /2/users/me for the broadcaster’s profile.

Errors

The /2/broadcasts routes return every error in the standard X API problem format; see each route’s page for its errors.

On the deprecated /2/users/:user_id/broadcasts* routes, invalid parameters return 400 in the standard X API problem format. Other errors return a { "error_type", "message" } body:

Status	error_type	Example
400	badRequest	The request can’t be applied to the broadcast in its current state.
403	forbidden	The account isn’t permitted to perform the action.
404	notFound	The broadcast or source doesn’t exist or belongs to another user.
412	preconditionFailed	The account isn’t eligible to broadcast.
503	serviceUnavailable	Temporary failure; retry with backoff.

Endpoints

Endpoint	Method & Path
Go Live	POST /2/broadcasts
Get Broadcasts	GET /2/broadcasts
Get Broadcast by ID	GET /2/broadcasts/:id
End Broadcast	PUT /2/broadcasts/:id/state
Delete Broadcast by ID	DELETE /2/broadcasts/:id

All routes require user context authentication: OAuth 2.0 with the broadcast.read and broadcast.write scopes (recommended), or OAuth 1.0a. They take the owner from the access token, wrap responses in data, return errors in the standard X API problem format, and support field selection with broadcast.fields on reads.

To schedule a broadcast in advance, with automatic or manual publishing, see the Livestream Scheduling API.

Deprecated routes

The original broadcast routes under /2/users/:user_id/broadcasts are deprecated and will be removed on January 1, 2027, after which they return 404. They keep working unchanged until then. See the migration guide for the differences.

Deprecated route	Replacement
POST /2/users/:user_id/broadcasts, then PUT /2/users/:user_id/broadcasts/:broadcast_id/state with PUBLISH	POST /2/broadcasts (one call)
GET /2/users/:user_id/broadcasts	GET /2/broadcasts
GET /2/users/:user_id/broadcasts/:broadcast_id	GET /2/broadcasts/:id
PUT /2/users/:user_id/broadcasts/:broadcast_id/state with END	PUT /2/broadcasts/:id/state
DELETE /2/users/:user_id/broadcasts/:broadcast_id	DELETE /2/broadcasts/:id