X scheduled broadcast API: one stream at a time

#Quick answer

You can book a live broadcast on X in advance with six routes under /2/broadcasts/scheduled, but you can no longer book a series. X's documentation still shows a recurrence object with a Daily or Weekly frequency and a worked weekly example; the live API contract at version 2.174 says requests including recurrence are rejected and that each occurrence must be created on its own. The two sources have disagreed in public for long enough that the only safe reading is the machine one.

Last updated: November 2026

Checked against the live API description at api.x.com/2/openapi.json, version 2.174, X's hand-written scheduling pages, X's own SKILL.md for the Livestream API, and the official Python SDK at 0.10.6, all read on 9 November 2026.

#Six endpoints

A schedule always binds to a stream source, so a source has to exist first. Reads need broadcast.read; create, update, delete and go-live need broadcast.write as well. OAuth 1.0a still works, and there the split is by app permission level rather than scope: read-only apps can list and get, and anything that changes state needs a Read and write app.

Unlike the broadcast and source routes, these six are not being removed. The 5 November 2026 rewrite of the Livestream API left them in place, with one change: source_id now means the source's new public id rather than its stream key. The whole of that migration, including why the old source id was a credential, is in our notes on the X Livestream API.

One detail that bites in JavaScript: every timestamp and numeric id here is a decimal string, deliberately, to survive a JSON parser. Keep them as strings end to end.

#Recurring schedules are documented and rejected

Read X's create page today and recurrence looks like a supported feature with a shape you can copy:

{
  "source_id": "9123456789012345678",
  "scheduled_start_ms": "1784000000000",
  "scheduled_end_ms": "1784003600000",
  "title": "Weekly livestream",
  "recurrence": {
    "frequency": "Weekly",
    "repeats": "4"
  }
}

The page explains that the response returns the first occurrence and that you list the rest. The overview page opens by saying the API "supports one-time and recurring schedules". The update page tells you to set roll_forward to true to shift the head of an existing series.

Now read the contract the server is built from. In the live description, the same recurrence field carries this: recurring schedules are being retired, requests that include recurrence will be rejected, and each occurrence should be created as its own scheduled broadcast. roll_forward says true will be rejected. recurring_schedule_id is "always null for new schedules". telecast_id, also documented as a real option on the create page, is marked ignored.

X's own SKILL.md for this API, published on the same docs site for agents to read, sides with the contract in one line: recurrence and roll_forward are retired, schedule each occurrence separately.

So three of X's four published surfaces agree that this is gone, and the fourth is the one a human reads first.

The failure mode is loud rather than silent, which is the one piece of luck here. CreateScheduledBroadcastRequest sets additionalProperties: false, so a stale recurrence block is not quietly dropped. It comes back as a 400. Verify against the live description rather than the prose whenever the two could disagree, because this is not a documentation typo. It is a retired feature with a live example still sitting on the page.

#Two ids, and the path only takes one

Create returns both, and they are not interchangeable:

Nothing converts one into the other, and nothing accepts the wrong one gracefully. X's docs say it twice, once as a tip on the create page and once in the overview: save both values. The SDK's internal naming is a small hint about why they differ, since it labels broadcast_id an "alphanumeric UBS broadcast id", pointing at a separate broadcast service behind the scheduler.

Store them as a pair on your side from the first response. Retrieving a schedule later gives you both, so this is recoverable, but only if you still know which schedule you are looking for.

#The update is a full replacement

PUT /2/broadcasts/scheduled/:id looks like a partial update. Three fields are required and nine are optional, which in most APIs means you send what you want to change.

Not here. X's own warning on the update page is explicit: this is a full replacement, so read the current broadcast, change what you need, and resend every field that should remain set. Omitting a previously set optional field can clear it. The error table backs it up with a named case, "incomplete full-replacement update", answered with 400.

Two practical consequences. First, renaming a scheduled stream requires scheduled_broadcast_id, scheduled_start_ms and scheduled_end_ms in the body alongside the new title, because all three are mandatory on every update. Second, any update path in your code needs a read immediately before it. A write-only update function will eventually erase a description or a thumbnail that someone set elsewhere.

Worth noting that X's SKILL.md describes the same endpoint as partial, with those three fields required. The hand-written page and the error table are the stricter reading, and the stricter reading is the safe one to build against.

#chat_option is a string here and an integer next door

Both livestream create routes take the same seven chat settings. They disagree about the type.

The values mean the same thing in both places: 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.

Since both request bodies reject unknown fields, you cannot even defend yourself by sending both forms. A payload shared between a schedule and an immediate go-live has to be rewritten, not reused, and the thing that breaks is a quoted digit.

#The SDK types the retired fields

The official Python SDK is further from this API than its module list suggests. At 0.10.6, uploaded 25 July 2026 and still current, xdk.broadcasts covers the scheduled routes well: create, get, update, delete, list and go-live are all generated. Then the models drift:

• scheduled_end_ms is a required field. The API and the docs both treat it as optional, which is how you get an open-ended broadcast. Through the SDK, you cannot schedule one.
• recurrence is fully modelled, down to frequency: Literal["Daily", "Weekly"]. The server rejects it.
• roll_forward is typed and described as shifting the head of a recurring series. The server rejects it when true.
• telecast_id is typed and described as a real association. The server ignores it.
• source_id is described as "Ingest / source id to bind (same as sources rtmp_stream_key)". That meaning expires on 1 January 2027.
• Models are configured with extra="allow" while the spec sets additionalProperties: false, so the client will happily serialise a field the server rejects.

The last one is the pattern that matters: a type-checked, SDK-validated, schema-plausible request can still be a 400. The wheel also reports __version__ = "0.1.0" internally while PyPI serves it as 0.10.6, which tells you how much of this is generated and unreviewed. Read the published package rather than the reference pages, a habit we go into in X API Python.

#Auto-publish, manual publish, and what breaks go-live

Two flows, chosen at create time by one boolean.

Leave manual_publish out, or set it false, and X's scheduler publishes at scheduled_start_ms. Your encoder has to be pushing video to the source before that instant, because the scheduler will not wait for you.

Set it true and the schedule sits there until you call POST /2/broadcasts/scheduled/:id/live. Video must already be flowing when you make that call; the source has to be active for the broadcast to publish. X's troubleshooting list for a failed go-live is short and in a useful order: confirm manual_publish is actually true, confirm the source id, confirm RTMP video is reaching the source, confirm the broadcast has not already ended or been deleted. A go-live request against a schedule that was not configured for manual publishing is a documented 400.

After publishing, poll the get endpoint and watch state. The live description gives five values, Created or Scheduled before the start, then Running, Ended or Error; the overview page lists only four and omits Scheduled. Handle five.

Eligibility is upstream of all of it. A protected account cannot broadcast at all, and live video on X has been gated behind a paid subscription in the app since mid-2024, which how to go live on X covers along with the Live Studio control room that does scheduling without any of this. If the account cannot go live by hand, no amount of correct JSON will help.

#No price, no rate-limit row

The pay-per-use rate card is detailed to the tenth of a cent. It has twelve named read resources and fifteen named write actions, and not one of them is a broadcast, a source or a schedule. The rate-limit reference carries fourteen per-namespace tables plus an eleven-row catch-all, and no /2/broadcasts route appears in any of them.

That leaves one published number for the entire Livestream API, from the docs prose: 450 requests per 15 minutes per user on the source routes and on the one-call go-live route. Nothing states a ceiling for the scheduling routes specifically.

If you are budgeting, measure. Run one schedule through create, update and delete, and read your credit balance before and after, because guessing from the nearest row on the card is a 40-fold spread. How the rest of the card bills, and what the 24-hour deduplication window does, is in X API pricing, and the namespaces that do publish limits are in X API rate limits.

#What to build instead of a recurring schedule

Since recurrence is gone, repetition becomes your job. The shape that survives:

1. Keep the series definition in your own store: source id, weekday, time, duration, title template.
2. A few days out, create one scheduled broadcast per occurrence, and keep both ids it returns.
3. Reconcile with GET /2/broadcasts/scheduled rather than trusting your own record, so a schedule deleted in the app does not get published twice.
4. Treat updates as read-then-write, always, given the full-replacement rule.
5. Pass the source id as source_id, never the stream key, whatever the SDK's field description says.

This is more code than {"frequency": "Weekly", "repeats": "4"}, and it is the only version that works today.

A last piece of perspective. Booking a livestream through an API is worth it when the stream is the product: a weekly show with a crew, a match feed, an event. For most accounts the thing being scheduled is not video at all but ordinary posts, and that is a much better served problem, with free routes covered in how to schedule posts on X. X-Autopilot takes the same idea further by running on your own Mac in your own browser session, so there is no shared cloud IP pool and no delegate account in the path. That is a smaller detection surface than a hosted scheduler, not an absent one, and automating engagement through a browser sits in a gray area under X's automation rules rather than being something X sanctions. The scheduling API is sanctioned. It also now expects you to book every single week by hand.