Get stream
Reading the response
The response covers three axes you’ll mix when authoring stream URLs:- Wall-clock time —
created_at_ms,first_frame_at_ms,last_frame_at_ms,expires_at_ms. Unix ms. Useful for absolute deadlines andtimestamp_msmath (thetimestamp_msanchor is measured fromfirst_frame_at_ms). - Stream-clock time —
stream_time_ms. Monotonically increases from0at the first frame; resets to no other clock if the publisher pauses. - Frame indices —
last_frame_index,first_available_frame_index. Lifetime indices that never reset, even after eviction. The pair defines the retention window — anything in[first_available_frame_index, last_frame_index]resolves cleanly; older indices clamp up tofirst_available_frame_index.
*_at_ms / *_index field returns null (only id, state, created_at_ms, expires_at_ms, ttl_seconds are populated). Polling last_frame_at_ms is the cheapest “wait for ingest” check.
After the stream ends, state becomes ended with ended_at_ms and end_reason set. The endpoint keeps returning the ended record for a short tombstone window, then 404s.Authorizations
Every public HTTP request requires Authorization: Bearer <api_key>, except
GET /models and the public /billing/pricing endpoints.
401means the key is missing, unknown, or revoked.403means the key is valid but cannot access the requested resource.- The publish token returned by
POST /streamsis only for publishing media to LiveKit. It does not replace the API key for HTTP calls.
Headers
Optional hint to route the request to the region that owns the stream. If the
request reaches the wrong region the API returns 409 with a region_error body.
us-west1, us-central1 Path Parameters
UUID returned by POST /streams.
Response
Stream state.
Lifecycle state. active while the stream accepts publishers and inference.
ended once it has expired or been deleted — this transition is terminal.
active, ended Stream-clock position in ms. Zero until the first frame arrives, then monotonically increasing from that first frame.
Wall-clock Unix ms of the first frame ever ingested.
Wall-clock Unix ms of the most recent frame.
Lifetime index of the most recent frame. frame_index=-1 resolves against this at request time.
Wall-clock Unix ms of the oldest retained frame.
Lifetime index of the oldest frame still retained.
Wall-clock Unix ms of stream creation.
Rolling FPS over the current frame-metrics bucket for active streams.
Wall-clock Unix ms when the lease will expire. null on ended streams.
Wall-clock Unix ms when the stream entered the ended state.
Why the stream ended. expired = system-driven termination, deleted =
explicit DELETE. null while state == active.
expired, deleted Reserved for future audio support. Always false today.