Skip to main content
GET
Get stream

Reading the response

The response covers three axes you’ll mix when authoring stream URLs:
  • Wall-clock timecreated_at_ms, first_frame_at_ms, last_frame_at_ms, expires_at_ms. Unix ms. Useful for absolute deadlines and timestamp_ms math (the timestamp_ms anchor is measured from first_frame_at_ms).
  • Stream-clock timestream_time_ms. Monotonically increases from 0 at the first frame; resets to no other clock if the publisher pauses.
  • Frame indiceslast_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 to first_available_frame_index.
Until the publisher delivers a first frame, every *_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

Authorization
string
header
required

Every public HTTP request requires Authorization: Bearer <api_key>, except GET /models and the public /billing/pricing endpoints.

  • 401 means the key is missing, unknown, or revoked.
  • 403 means the key is valid but cannot access the requested resource.
  • The publish token returned by POST /streams is only for publishing media to LiveKit. It does not replace the API key for HTTP calls.

Headers

X-Overshoot-Region
enum<string>

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.

Available options:
us-west1,
us-central1

Path Parameters

stream_id
string<uuid>
required

UUID returned by POST /streams.

Response

Stream state.

id
string<uuid>
required
state
enum<string>
required

Lifecycle state. active while the stream accepts publishers and inference. ended once it has expired or been deleted — this transition is terminal.

Available options:
active,
ended
stream_time_ms
number | null

Stream-clock position in ms. Zero until the first frame arrives, then monotonically increasing from that first frame.

first_frame_at_ms
integer | null

Wall-clock Unix ms of the first frame ever ingested.

last_frame_at_ms
integer | null

Wall-clock Unix ms of the most recent frame.

last_frame_index
integer | null

Lifetime index of the most recent frame. frame_index=-1 resolves against this at request time.

first_available_frame_at_ms
integer | null

Wall-clock Unix ms of the oldest retained frame.

first_available_frame_index
integer | null

Lifetime index of the oldest frame still retained.

created_at_ms
integer | null

Wall-clock Unix ms of stream creation.

recent_fps
number | null

Rolling FPS over the current frame-metrics bucket for active streams.

retained_frame_count
integer | null
evicted_frame_count
integer | null
expires_at_ms
integer | null

Wall-clock Unix ms when the lease will expire. null on ended streams.

ttl_seconds
integer | null
ended_at_ms
integer | null

Wall-clock Unix ms when the stream entered the ended state.

end_reason
enum<string> | null

Why the stream ended. expired = system-driven termination, deleted = explicit DELETE. null while state == active.

Available options:
expired,
deleted
audio
boolean
default:false

Reserved for future audio support. Always false today.