Skip to main content
GET
/
streams
/
{stream_id}
Get stream
curl --request GET \
  --url https://api.overshoot.ai/v1/streams/{stream_id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "state": "active",
  "stream_time_ms": 123,
  "last_frame_at_ms": 123,
  "last_frame_index": 123,
  "first_frame_at_ms": 123,
  "first_available_frame_at_ms": 123,
  "first_available_frame_index": 123,
  "created_at_ms": 123,
  "recent_fps": 123,
  "retained_frame_count": 123,
  "evicted_frame_count": 123,
  "expires_at_ms": 123,
  "ttl_seconds": 123,
  "ended_at_ms": 123,
  "end_reason": "expired",
  "audio": false
}

Documentation Index

Fetch the complete documentation index at: https://docs.overshoot.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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 and timestamp_ms math (the timestamp_ms anchor is measured from first_frame_at_ms).
  • Stream-clock time — stream_time_ms. Monotonically increases from 0 at 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 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

All requests must include Authorization: Bearer <api_key>. Get a key from the Overshoot dashboard. Listing models (GET /models) does not require auth.

Path Parameters

​
stream_id
string<uuid>
required

UUID returned by POST /streams.

Response

Stream state.

​
id
string<uuid>
required

Stream identifier. Stable for the stream's lifetime.

​
state
enum<string>
required

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

Available options:
active,
ended
​
stream_time_ms
number | null

Stream-clock position in ms — monotonically increases from 0 at the first frame. null until the first frame arrives.

​
last_frame_at_ms
integer | null

Wall-clock Unix ms of the most recent frame ingested. null until a frame has arrived.

​
last_frame_index
integer | null

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

​
first_frame_at_ms
integer | null

Wall-clock Unix ms of the first frame ever ingested on this stream. Used as the origin for timestamp_ms anchors in stream URLs.

​
first_available_frame_at_ms
integer | null

Wall-clock Unix ms of the oldest frame still in the retention buffer. Frames older than this have been evicted.

​
first_available_frame_index
integer | null

Lifetime index of the oldest frame still retained. References to indices below this clamp up to it (intersection-with-availability).

​
created_at_ms
integer | null

Wall-clock Unix ms when the stream resource was created (before any frame arrived).

​
recent_fps
number | null

Rolling FPS measured over the last few seconds of ingest.

​
retained_frame_count
integer | null

Number of frames currently held in the retention buffer.

​
evicted_frame_count
integer | null

Number of frames that have aged out of retention since the stream began.

​
expires_at_ms
integer | null

Wall-clock Unix ms when the lease expires if not renewed.

​
ttl_seconds
integer | null

Lease TTL in seconds. Currently 300.

​
ended_at_ms
integer | null

Wall-clock Unix ms when the stream entered the ended state. null while state == active.

​
end_reason
enum<string> | null

Why the stream ended. expired = TTL elapsed, deleted = explicit DELETE, reaped = system cleanup. null while state == active.

Available options:
expired,
deleted,
reaped
​
audio
boolean
default:false

Reserved for future audio support. Always false today.