Create a Scheduled Broadcast

POST /2/broadcasts/scheduled schedules a broadcast on one of your sources, with automatic or manual publishing.

POST /2/broadcasts/scheduled

Create a Scheduled Broadcast

cURL

curl --request POST \
  --url https://api.x.com/2/broadcasts/scheduled \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scheduled_start_ms": "<string>",
  "source_id": "<string>",
  "available_for_replay": true,
  "chat_option": "<string>",
  "description": "<string>",
  "is_locked": true,
  "locale": "<string>",
  "manual_publish": true,
  "scheduled_end_ms": "<string>",
  "telecast_id": "<string>",
  "thumbnail_media_id": "<string>",
  "title": "<string>"
}
'

201

{
  "data": {
    "available_for_replay": true,
    "broadcast_id": "<string>",
    "chat_option": "<string>",
    "description": "<string>",
    "locale": "<string>",
    "manual_publish": true,
    "recurring_schedule_id": "<string>",
    "scheduled_broadcast_id": "<string>",
    "scheduled_end_ms": "<string>",
    "scheduled_start_ms": "<string>",
    "source_id": "<string>",
    "state": "<string>",
    "telecast_id": "<string>",
    "thumbnail_media_id": "<string>",
    "title": "<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>"
    }
  ]
}

Schedules a broadcast on one of the authenticated user’s sources. The response returns 201 Created with the new scheduled broadcast.

Required fields

source_id and scheduled_start_ms are required.

• source_id is the source id of one of your stream sources: its id from Get Sources. The response returns source_id as the source id.
• scheduled_start_ms is the scheduled start time, Unix epoch milliseconds as a decimal string. It must be in the future.

Passing a stream key as source_id is deprecated and stops working on January 1, 2027. Pass the source id instead. See the migration guide.

Schedule rules

• The start time must be in the future.
• With scheduled_end_ms, the broadcast must last between 1 minute and 24 hours. Omit scheduled_end_ms for an open-ended broadcast.
• Scheduled broadcasts on the same source can’t overlap. For this check, an open-ended broadcast occupies the minute after its start, so open-ended broadcasts on one source must start at least 1 minute apart.

A request that breaks one of these rules returns 400. The error message starts with the reason, such as start_in_past, invalid_period or schedule_conflict.

Publishing behavior

Set manual_publish to true when you want to publish explicitly with POST /2/broadcasts/scheduled/:id/live. Otherwise, the scheduler publishes automatically at scheduled_start_ms.

Optional fields

• scheduled_end_ms sets the scheduled end time as Unix epoch milliseconds. If omitted, the broadcast has no scheduled end and runs until it is stopped or ends manually.
• title and description set the broadcast’s status text and description.
• thumbnail_media_id is a numeric media ID used as the pre-live slate image.
• chat_option controls chat permissions and is a numeric string.
• available_for_replay enables replay after the broadcast ends.
• is_locked locks the broadcast.
• locale sets the broadcast’s locale.

Recurring schedules are retired. A request that includes recurrence returns 400; create each occurrence as its own scheduled broadcast. telecast_id is ignored.

Example

{
  "source_id": "9123456789012345678",
  "scheduled_start_ms": "1784000000000",
  "scheduled_end_ms": "1784003600000",
  "title": "Product launch",
  "description": "Live from our launch event",
  "available_for_replay": true,
  "manual_publish": true
}

Save both broadcast_id (alphanumeric, used in endpoint paths) and scheduled_broadcast_id (numeric, required in the body of update requests).

Authorizations

OAuth2UserTokenUserToken

Authorization · string · header · required

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

Scopes

broadcast.read

View your live broadcasts and their chat.

broadcast.write

Manage your live broadcasts and send chat messages on your behalf.

Body

application/json

scheduled_start_ms · string · required

Start time, ms since Unix epoch (decimal string).

Pattern: ^[0-9]{1,19}$

source_id · string · required

Source to bind: a source's id from GET /2/sources. A stream key is also accepted but deprecated; stream keys stop being accepted when the /2/users/:id/sources and /2/users/:id/broadcasts routes reach end of life on January 1, 2027.

Minimum string length: 1

available_for_replay · boolean

Enable replay.

chat_option · string

Who can chat (numeric string): 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.

Pattern: ^[0-9]{1,19}$

description · string

Description.

is_locked · boolean

Lock the broadcast.

locale · string

Locale.

manual_publish · boolean

If true, do not auto-publish at start; call POST .../live when ready.

recurrence · object

Deprecated: recurring schedules are being retired and requests that include recurrence will be rejected. Create each occurrence as its own scheduled broadcast.

Show child attributes

scheduled_end_ms · string

Optional end time, ms since Unix epoch (decimal string). Omit for an open-ended broadcast.

Pattern: ^[0-9]{1,19}$

telecast_id · string

Deprecated: telecast associations are being retired and this field will be ignored.

Pattern: ^[0-9]{1,19}$

thumbnail_media_id · string

Pre-live slate media id (numeric string).

Pattern: ^[0-9]{1,19}$

title · string

Title / status text.

Response

201

application/json

The request has succeeded.

data · object

Show child attributes

errors · object[]

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