YouTube Live Broadcasts and Streams
Schedule and run YouTube live events from your app. Upload-Post creates and manages the broadcast (the live event, which is also the YouTube video) and the stream (the ingestion point) and gives you the ingestion URL and stream key. Your encoder sends the video (OBS, vMix, a hardware encoder, ffmpeg…): Upload-Post does not carry the video signal.
Typical flow:
POST /live/broadcastswithcreate_stream=true: creates the broadcast, creates a stream, binds them and returns the ingestion URL and key.- Point your encoder at
ingestion.rtmps_ingestion_address(oringestion_address) withingestion.stream_keyand start streaming. GET /live/streams/{id}untilstatus.streamStatusisactive(checkstatus.healthStatus).POST /live/broadcasts/{id}/transitionwithstatus=testing(only if the monitor stream is on, which is the default), thenstatus=livewithconfirm=true.- When you finish,
status=completewithconfirm=true, then stop the encoder.
With enable_auto_start / enable_auto_stop YouTube starts and ends the broadcast by itself when the video arrives and stops, and you can skip step 4-5.
All paths start with /api/uploadposts/youtube/live. Send user (the profile username with the YouTube channel) in the query string or the JSON body, and Authorization: Apikey your-api-key-here. They follow the common rules of the YouTube endpoints.
Requirements
The channel must have live streaming enabled (YouTube asks for a verified channel, no live streaming restrictions in the last 90 days and being 16 or older; enable it at youtube.com/features; the first activation can take a while). Streaming from the YouTube mobile app has extra requirements set by YouTube. Without it the API answers 403 youtube_live_not_enabled or youtube_live_blocked. No extra permission is needed when connecting the channel.
The stream key is a secret
Anyone with the stream key can go live on the channel.
- It is only in the direct answer to you: Upload-Post never logs it, stores it or sends it in webhooks.
- Only the account owner gets it. Team members acting for the owner get
"<hidden>"instead (also inside HLS/DASH ingestion URLs, which embed the key, and in the closed-caption ingestion URL), and the stream carries"stream_key_hidden": true. The owner can always read it here or in YouTube Studio. - The owner gets it when creating a stream, and on reads only when asking with
include_stream_key=true.
Broadcasts
List
GET /api/uploadposts/youtube/live/broadcasts
| Name | Type | Required | Description |
|---|---|---|---|
user | String | Yes | Profile username. |
status | String | No | active, all, completed or upcoming. |
ids | String | No | Up to 50 broadcast IDs, comma separated (not with status). Without status and ids: all your broadcasts. |
broadcast_type | String | No | all, event (YouTube's default) or persistent. |
parts | String | No | Subset of snippet, contentDetails, status, monetizationDetails. Default: the first three. |
max_results | Integer | No | 0-50, default 50. |
page_token | String | No | next_page_token of the previous page. |
Answer: {"success": true, "items": [...], "next_page_token": "...", "page_info": {...}} with YouTube's liveBroadcast resource as is. With ids, not_found lists the IDs YouTube did not return.
GET /api/uploadposts/youtube/live/broadcasts/{broadcast_id} returns one broadcast ({"success": true, "broadcast": {...}}): lifecycle status, bound stream, snippet.liveChatId for the live chat.
Create
POST /api/uploadposts/youtube/live/broadcasts
| Field | Type | Required | Description |
|---|---|---|---|
title | String | Yes | 1-100 characters (< > become ‹ ›, as on uploads). |
scheduled_start_time | String | Yes | ISO 8601 with time zone, in the future (e.g. 2026-12-01T18:00:00Z). Dates must fall between 1970 and 2100 (400 invalid_parameter). |
privacy_status | String | Yes | private, public or unlisted. |
description | String | No | Up to 5,000 characters. |
category_id | String | No | YouTube video category ID (YouTube's default: Entertainment). |
scheduled_end_time | String | No | After the start. Without it the broadcast has no scheduled end. |
made_for_kids | Boolean | No | Self-declared "made for kids". Only at creation. |
enable_monitor_stream | Boolean | No | Default true: you must go through testing before live. |
broadcast_stream_delay_ms | Integer | No | Delay of the public stream, default 0. |
enable_auto_start / enable_auto_stop | Boolean | No | Start when video arrives / end about a minute after it stops. |
enable_dvr | Boolean | No | Viewers can pause and rewind. Default true. |
enable_embed | Boolean | No | Can be embedded. Default true. |
record_from_start | Boolean | No | Default true; false needs YouTube's permission for the channel. |
latency_preference | String | No | normal, low or ultraLow (no captions, max 1080p). |
projection | String | No | rectangular (default) or 360. |
closed_captions_type | String | No | closedCaptionsDisabled, closedCaptionsHttpPost or closedCaptionsEmbedded. |
availability | Object | No | Regions: {"excluded_regions": ["DE"], "interval": {"start_time", "end_time"}, "region_intervals": [{"region_code": "ES", "start_time", "end_time"}]}. Times at most five years ahead; YouTube does not accept time windows on upcoming or active broadcasts. |
create_stream | Boolean | No | Also create a stream and bind it. Then stream_title (default: the broadcast title), stream_description, stream_ingestion_type, stream_resolution, stream_frame_rate and stream_reusable work as in Create a stream. |
To set the broadcast's thumbnail use Set YouTube thumbnail with the broadcast ID (a broadcast is a YouTube video).
curl -X POST https://api.upload-post.com/api/uploadposts/youtube/live/broadcasts \
-H 'Authorization: Apikey your-api-key-here' -H 'Content-Type: application/json' \
-d '{"user": "my-profile", "title": "Launch day", "scheduled_start_time": "2026-12-01T18:00:00Z",
"privacy_status": "unlisted", "create_stream": true}'
{
"success": true,
"broadcast": {"id": "abc123def45", "snippet": {"title": "Launch day", "liveChatId": "Cg0KC2..."},
"status": {"lifeCycleStatus": "ready", "privacyStatus": "unlisted"},
"contentDetails": {"boundStreamId": "x5Gq...", "monitorStream": {"enableMonitorStream": true}}},
"stream": {"id": "x5Gq...", "cdn": {"ingestionType": "rtmp", "ingestionInfo": {"streamName": "abcd-efgh-ijkl-mnop", "...": "..."}}},
"ingestion": {
"ingestion_type": "rtmp",
"ingestion_address": "rtmp://a.rtmp.youtube.com/live2",
"backup_ingestion_address": "rtmp://b.rtmp.youtube.com/live2?backup=1",
"rtmps_ingestion_address": "rtmps://a.rtmps.youtube.com/live2",
"stream_key": "abcd-efgh-ijkl-mnop"
}
}
If the broadcast is created but the stream or the binding fails, the answer is still 201 with the broadcast, stream_error or bind_error, and a warnings entry: nothing is rolled back for you.
Edit
PATCH /api/uploadposts/youtube/live/broadcasts/{broadcast_id}
Send only what changes: title, description, category_id, scheduled_start_time, scheduled_end_time, privacy_status, the contentDetails fields of the table above, and, for channels in the YouTube Partner Program, ads_monetization_status (on/off), cuepoint_schedule_enabled, pause_ads_until (at most 10 minutes ahead; a past date or "" resumes ads), yt_optimized_cuepoint_config (LOW, MEDIUM, HIGH), schedule_strategy (CONCURRENT, NON_CONCURRENT) and repeat_interval_secs (360-3600). Upload-Post reads the broadcast and keeps everything you did not send (YouTube erases what is not resent). An empty title or description ("") means no change; "description": null clears the description. Text fields must be strings (400 invalid_field). Edits of the same channel's broadcasts run one at a time: a second edit sent while one is in progress answers 409 youtube_channel_busy without spending anything; retry it a moment later.
The settings (enable_*, latency, captions, availability…) can only change while the broadcast is created or ready, and the schedule until it goes live: otherwise 409 youtube_live_settings_locked. made_for_kids can only change with the video edit.
Delete
DELETE /api/uploadposts/youtube/live/broadcasts/{broadcast_id}?user=my-profile&confirm=true
Cannot be undone. Without confirm=true: 400 confirmation_required.
Bind or unbind a stream
POST /api/uploadposts/youtube/live/broadcasts/{broadcast_id}/bind
{"user": "my-profile", "stream_id": "x5Gq..."} binds; {"user": "my-profile", "unbind": true} removes the binding. A broadcast has one stream; a stream can serve several broadcasts.
Go testing, live or complete
POST /api/uploadposts/youtube/live/broadcasts/{broadcast_id}/transition
| Field | Required | Description |
|---|---|---|
status | Yes | testing, live or complete. |
confirm | For live and complete | true. Going live makes the broadcast visible; completing ends it for good. |
The stream must be active (receiving video). The answer comes at once with life_cycle_status (usually testStarting or liveStarting): YouTube takes from a few seconds to a minute. Poll GET /live/broadcasts/{id} every 5-10 s until status.lifeCycleStatus is the target.
Insert an ad break
POST /api/uploadposts/youtube/live/broadcasts/{broadcast_id}/cuepoint
While live, on a monetized broadcast: duration_secs (default 30) and at most one of insertion_offset_time_ms or walltime_ms (epoch ms). Without them the break starts as soon as possible.
Streams
Create a stream
POST /api/uploadposts/youtube/live/streams
| Field | Type | Required | Description |
|---|---|---|---|
title | String | Yes | 1-128 characters. Viewers never see it. |
description | String | No | Up to 10,000 characters. |
ingestion_type | String | No | rtmp (default; also gives the RTMPS address), hls or dash. |
resolution | String | No | 240p … 2160p or variable (default). |
frame_rate | String | No | 30fps, 60fps or variable (default). With resolution=variable it must be variable. |
reusable | Boolean | No | Default true. A non-reusable stream serves a single broadcast and only appears when listed by ID. |
The answer (201) has stream and ingestion (URL and key, owner only).
List, read, edit, delete
GET /live/streams: your streams (max_results0-50,page_token) orids(up to 50).parts:snippet,cdn,status(default) andcontentDetails. Keys hidden unlessinclude_stream_key=true(owner).GET /live/streams/{stream_id}: one stream withingestionand its health:status.streamStatus(active,ready,inactive…),status.healthStatus.status(good,ok,bad,noData) andstatus.healthStatus.configurationIssues(YouTube's list of issues).PATCH /live/streams/{stream_id}: onlytitleanddescription(""= no change,"description": nullclears it). The format cannot change: create a new stream.DELETE /live/streams/{stream_id}?confirm=true: every encoder using its key stops working. YouTube refuses while it is bound to a broadcast that has not finished.
Daily allowance
Every live broadcast and stream call costs 1 unit of the account's daily YouTube allowance (an edit costs 2: a read and the update; create with create_stream costs 3).
Error Responses
All errors carry success: false, error and a stable error_code; those from YouTube add youtube_status and youtube_reason.
- 400 —
missing_parameter,invalid_parameter,invalid_field,invalid_parts,invalid_filter,too_many_ids,nothing_to_update,confirmation_required,invalid_json; YouTube's own validation (youtube_invalid_scheduled_start_time,youtube_invalid_latency_preference_options, …). - 403 —
youtube_live_not_enabled,youtube_live_blocked,youtube_live_not_allowed,youtube_live_invalid_transition,youtube_live_redundant_transition,youtube_live_stream_inactive(start the encoder first),youtube_live_concurrent_limit,youtube_live_shared_ingestion_limit,youtube_live_scheduled_limit,youtube_live_broadcast_delete_not_allowed,youtube_live_stream_delete_not_allowed,youtube_live_stream_update_not_allowed,youtube_live_bind_not_allowed,youtube_live_monetization_not_allowed. - 404 —
youtube_live_broadcast_not_found,youtube_live_stream_not_found. - 409 —
youtube_live_settings_locked;youtube_channel_busy(another edit of this channel's broadcasts is in progress; nothing was changed or charged). - 429 — daily allowance or YouTube limits (
youtube_daily_budget_exhausted,youtube_shared_budget_exhausted,youtube_quota_exhausted,youtube_rate_limited), withretry_after. - 502 —
youtube_live_not_eligible_for_ads(YouTube status 412: the broadcast cannot have mid-roll ads).youtube_write_outcome_unknown: YouTube did not answer a change in time and may have done it. Check with GET before retrying; it is never resent automatically.youtube_unreachable/youtube_upstream_error: retry later. - 503 —
youtube_feature_disabled: YouTube management features are temporarily off on Upload-Post. Uploads keep working.