Skip to main content

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:

  1. POST /live/broadcasts with create_stream=true: creates the broadcast, creates a stream, binds them and returns the ingestion URL and key.
  2. Point your encoder at ingestion.rtmps_ingestion_address (or ingestion_address) with ingestion.stream_key and start streaming.
  3. GET /live/streams/{id} until status.streamStatus is active (check status.healthStatus).
  4. POST /live/broadcasts/{id}/transition with status=testing (only if the monitor stream is on, which is the default), then status=live with confirm=true.
  5. When you finish, status=complete with confirm=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
NameTypeRequiredDescription
userStringYesProfile username.
statusStringNoactive, all, completed or upcoming.
idsStringNoUp to 50 broadcast IDs, comma separated (not with status). Without status and ids: all your broadcasts.
broadcast_typeStringNoall, event (YouTube's default) or persistent.
partsStringNoSubset of snippet, contentDetails, status, monetizationDetails. Default: the first three.
max_resultsIntegerNo0-50, default 50.
page_tokenStringNonext_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
FieldTypeRequiredDescription
titleStringYes1-100 characters (< > become ‹ ›, as on uploads).
scheduled_start_timeStringYesISO 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_statusStringYesprivate, public or unlisted.
descriptionStringNoUp to 5,000 characters.
category_idStringNoYouTube video category ID (YouTube's default: Entertainment).
scheduled_end_timeStringNoAfter the start. Without it the broadcast has no scheduled end.
made_for_kidsBooleanNoSelf-declared "made for kids". Only at creation.
enable_monitor_streamBooleanNoDefault true: you must go through testing before live.
broadcast_stream_delay_msIntegerNoDelay of the public stream, default 0.
enable_auto_start / enable_auto_stopBooleanNoStart when video arrives / end about a minute after it stops.
enable_dvrBooleanNoViewers can pause and rewind. Default true.
enable_embedBooleanNoCan be embedded. Default true.
record_from_startBooleanNoDefault true; false needs YouTube's permission for the channel.
latency_preferenceStringNonormal, low or ultraLow (no captions, max 1080p).
projectionStringNorectangular (default) or 360.
closed_captions_typeStringNoclosedCaptionsDisabled, closedCaptionsHttpPost or closedCaptionsEmbedded.
availabilityObjectNoRegions: {"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_streamBooleanNoAlso 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
FieldRequiredDescription
statusYestesting, live or complete.
confirmFor live and completetrue. 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
FieldTypeRequiredDescription
titleStringYes1-128 characters. Viewers never see it.
descriptionStringNoUp to 10,000 characters.
ingestion_typeStringNortmp (default; also gives the RTMPS address), hls or dash.
resolutionStringNo240p … 2160p or variable (default).
frame_rateStringNo30fps, 60fps or variable (default). With resolution=variable it must be variable.
reusableBooleanNoDefault 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_results 0-50, page_token) or ids (up to 50). parts: snippet, cdn, status (default) and contentDetails. Keys hidden unless include_stream_key=true (owner).
  • GET /live/streams/{stream_id}: one stream with ingestion and its health: status.streamStatus (active, ready, inactive…), status.healthStatus.status (good, ok, bad, noData) and status.healthStatus.configurationIssues (YouTube's list of issues).
  • PATCH /live/streams/{stream_id}: only title and description ("" = no change, "description": null clears 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), with retry_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.