Livestream Scheduling API

Create, manage, and publish scheduled broadcasts on X, with automatic or manual publishing and OAuth 2.0 support.

Use the Livestream Scheduling API to create, manage, and publish scheduled broadcasts on X.

A scheduled broadcast is associated with an existing livestream source. It can publish automatically at its scheduled start time or wait for an explicit go-live request.

Before you begin

Access

See Getting Started for the prerequisites.

Authentication

All requests require user-context authentication. The authenticated user owns the broadcasts accessed through these endpoints.

Supported authentication methods:

• OAuth 2.0 Authorization Code Flow with PKCE. Read routes require broadcast.read. Create, update, delete, and go-live routes require both broadcast.read and broadcast.write.
• OAuth 1.0a user context. List and get routes accept apps with Read, Read and write, or Read, write, and Direct Messages permissions. Create, update, delete, and go-live routes require Read and write or Read, write, and Direct Messages permissions.

OAuth 2.0 is recommended for new integrations. See Authentication for details on both flows.

Base URL

https://api.x.com

Livestream source

You must create a livestream source before scheduling a broadcast. Pass the source’s id (its source id, from Get Sources) as source_id. Responses return source_id as the source id too.

Passing a source’s stream key as source_id in create and update requests is deprecated. It keeps working until January 1, 2027, when the /2/users/:user_id/sources and /2/users/:user_id/broadcasts routes reach end of life. Pass the source id instead. See the migration guide.

For a manual go-live request, begin sending RTMP video to the source before calling the live endpoint. The source must be active for the broadcast to publish.

Timestamps and IDs

• Timestamp fields use Unix epoch time in milliseconds.
• Send timestamps and numeric IDs as decimal strings to preserve precision.
• The broadcast_id is an alphanumeric ID used in endpoint paths. IDs are 13 or 14 characters; don’t assume a fixed length.
• The scheduled_broadcast_id is a numeric scheduler ID. Save both values returned by create, list, or get. Updates require the numeric ID in the request body.

Schedule rules

• The start time must be in the future.
• A broadcast with a scheduled end lasts 1 minute to 24 hours. Omit the end for an open-ended broadcast.
• Scheduled broadcasts on the same source can’t overlap. Open-ended broadcasts on one source must start at least 1 minute apart.
• A scheduled broadcast can be updated only before it starts, and can’t be deleted while it’s live.
• Each broadcast is scheduled once. Recurring schedules are retired: recurrence and roll_forward=true return 400, and telecast_id is ignored.

Scheduled broadcast object

{
  "scheduled_broadcast_id": "2075599796786561024",
  "broadcast_id": "2AxRnanzLOrxlQ",
  "state": "Created",
  "title": "Product launch",
  "description": "Live from our launch event",
  "source_id": "9123456789012345678",
  "scheduled_start_ms": "1784000000000",
  "scheduled_end_ms": "1784003600000",
  "thumbnail_media_id": "2075599000000000000",
  "chat_option": "1",
  "locale": "en",
  "available_for_replay": true,
  "manual_publish": true
}

Fields that do not apply may be omitted.

Common state values include:

State	Meaning
Created	Scheduled and not yet live
Running	Currently live
Ended	The broadcast has ended
Error	The broadcast could not be started or completed

Endpoints

Endpoint	Method & Path
Create a scheduled broadcast	POST /2/broadcasts/scheduled
List scheduled broadcasts	GET /2/broadcasts/scheduled
Get a scheduled broadcast	GET /2/broadcasts/scheduled/:id
Update a scheduled broadcast	PUT /2/broadcasts/scheduled/:id
Delete a scheduled broadcast	DELETE /2/broadcasts/scheduled/:id
Go live on a scheduled broadcast	POST /2/broadcasts/scheduled/:id/live

Recommended workflow

Automatically published broadcast

1. Create or select a livestream source
2. Create a scheduled broadcast

   Leave manual_publish omitted or set to false.

3. Begin sending RTMP video

   Start pushing video before scheduled_start_ms.

4. The scheduler publishes the broadcast

   Publishing happens automatically at the scheduled start time.

5. Poll the get endpoint

   Observe state changes via Get a scheduled broadcast.

Manually published broadcast

1. Create or select a livestream source
2. Create a scheduled broadcast

   Set manual_publish: true.

3. Begin sending RTMP video
4. Go live when ready

   Call POST /2/broadcasts/scheduled/:id/live.

5. Poll the get endpoint

   Poll until the state is Running.

Errors and troubleshooting

Common HTTP responses:

Status	Meaning
400 Bad Request	Missing or invalid input, a schedule that breaks the schedule rules, an unknown broadcast, or a go-live request for a schedule that is not configured for manual publishing. The error message starts with the reason, such as start_in_past, invalid_period, schedule_conflict or not_found.
401 Unauthorized	Missing, expired, or invalid user access token.
403 Forbidden	The token lacks the required scope, the authenticated user is not permitted to access the resource, or the account isn’t allowed to go live.
429 Too Many Requests	Rate limit exceeded.
503 Service Unavailable	A dependent livestream or scheduling service could not complete the request.

If a go-live request fails:

• Confirm manual_publish is true.
• Confirm the source ID is correct.
• Confirm RTMP video is actively reaching the source.
• Confirm the broadcast has not already ended or been deleted.