---
title: "Get stream"
method: GET
path: "/streams/{stream_id}"
tags: ["Streams"]
---

# Get stream

`GET /streams/{stream_id}`

Returns current stream status and frame telemetry.

`stream_time_ms` is zero until the first frame arrives. After that, it is measured
from the first captured frame. When a stream ends, live counters and timestamps
are snapshotted — `GET /streams/{id}` on an ended stream returns those final
values; fields may be `null` if the stream ended before the value existed.

## Response `200`

Stream state.

- StreamStatusResponse
  - `id` string, uuid, required
  - `state` 'active' | 'ended', required — Lifecycle state. `active` while the stream accepts publishers and inference. `ended` once it has expired or been deleted — this transition is terminal.
  - `stream_time_ms` number, nullable — Stream-clock position in ms. Zero until the first frame arrives, then monotonically increasing from that first frame.
  - `first_frame_at_ms` integer, nullable — Wall-clock Unix ms of the first frame ever ingested.
  - `last_frame_at_ms` integer, nullable — Wall-clock Unix ms of the most recent frame.
  - `last_frame_index` integer, nullable — Lifetime index of the most recent frame. `frame_index=-1` resolves against this at request time.
  - `first_available_frame_at_ms` integer, nullable — Wall-clock Unix ms of the oldest retained frame.
  - `first_available_frame_index` integer, nullable — Lifetime index of the oldest frame still retained.
  - `created_at_ms` integer, nullable — Wall-clock Unix ms of stream creation.
  - `recent_fps` number, nullable — Rolling FPS over the current frame-metrics bucket for active streams.
  - `retained_frame_count` integer, nullable
  - `evicted_frame_count` integer, nullable
  - `expires_at_ms` integer, nullable — Wall-clock Unix ms when the lease will expire. `null` on ended streams.
  - `ttl_seconds` integer, nullable
  - `ended_at_ms` integer, nullable — Wall-clock Unix ms when the stream entered the `ended` state.
  - `end_reason` 'expired' | 'deleted', nullable — Why the stream ended. `expired` = system-driven termination, `deleted` = explicit `DELETE`. `null` while `state == active`.
  - `audio` boolean — Reserved for future audio support. Always `false` today.

## Other responses

- `401` — Missing or invalid API key.
- `404` — Stream unknown, expired, deleted, or owned by a different user.
- `409` — Wrong region.

---

[API](https://skmtc.net/overshoot/apis/overshoot-api.md) · [All operations](https://skmtc.net/overshoot/apis/overshoot-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/overshoot/overshoot-api/versions/defe49d6c837/schema)