RelayrtcDocs
Get started
Documentation
Streaming

Broadcast runs

Create an event, wait for its source, and control its output lifecycle.

On this page

A broadcast is one run of a stream. It snapshots the source, encoding profile, selected destinations and automatic recording policy when created. Editing those settings later does not modify an existing run.

Before starting, connect the source using streaming ingest. A broadcast cannot activate devices, launch an encoder or create an RTC room.

Create and start

Call this helper from an authorized backend action. Store the run and operation IDs with your event. Reuse the same commandId if retrying a start after a lost response.

TypeScript
import { relay } from './relay.js'
 
export async function startEvent(streamId: string, commandId: string) {
  const run = await relay.broadcasts.create({
    streamId,
    name: 'Town hall',
    waitTimeoutSeconds: 120,
    maxDurationSeconds: 14400,
  }, { idempotencyKey: `${commandId}:create` })
  const operation = await relay.broadcasts.start(run.id, {}, {
    idempotencyKey: `${commandId}:start`,
  })
  return { run, operation }
}

The run waits for a live source before allocating output work. Every run has one HLS output, attached to the canonical program rather than encoded again. Add destination IDs at creation for multistreaming.

Follow progress

StateMeaning
createdConfiguration saved; start has not been requested
waiting_for_sourceWaiting for a usable source
startingOutputs are starting
liveOutput readiness has been observed
reconnectingSource recovery is in progress
degradedOne or more outputs are unhealthy
stoppingOutput cleanup is in progress
stopped, failedTerminal; create another run for a new event

Read broadcasts.get(runId), broadcasts.getOutputs(runId) and streamingOperations.get(operationId). An accepted command or HTTP 202 is not proof that media is live. Reconcile these resources after reconnects or webhook delivery.

Stop a run

TypeScript
import { relay } from './relay.js'
 
export async function stopEvent(broadcastId: string, commandId: string) {
  return relay.broadcasts.stop(broadcastId, {}, {
    idempotencyKey: commandId,
  })
}

Stopping works while waiting, starting or live. It cancels output work and completes after acknowledgement or lease cleanup. It preserves the stream's source session and RTC room. If you also need to end source playback, stop the source separately.

Failures and retries

Outputs recover independently. A failing destination can degrade a run while healthy outputs continue. Use the destination retry workflow instead of restarting the whole event. If no configured output remains viable after recovery, the run fails.

Use a stable idempotency key for the same command and payload. Optional version checks reject commands based on stale state. On a conflict, reload and decide whether the action is still appropriate.

Defaults allow 16 active broadcasts globally and four per environment, with separate output-job limits. Waiting for a source does not allocate an output slot. Quotas admit work; they do not provision CPU or worker capacity.

For automation, consume signed broadcast lifecycle webhooks and deduplicate event IDs. See webhooks, REST contracts and Node methods.