> ## 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. # 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 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 `404`s. ## OpenAPI ````yaml GET /streams/{stream_id} openapi: 3.0.3 info: title: Overshoot API version: 1.0.0-beta description: > Real-time video understanding API. Create a live video stream, push frames over WebRTC (LiveKit), then ask a vision-language model questions about what's happening using an OpenAI-compatible chat completions endpoint. Billing endpoints are mounted on the same host under `/billing`. servers: - url: https://api.overshoot.ai/v1beta security: - bearerAuth: [] tags: - name: Streams description: Create, inspect, keep alive, and delete live video streams. - name: Models description: List available vision-language models. - name: Chat description: Ask models questions about a stream's frames. - name: Billing description: Pricing, prepaid balance, and checkout. paths: /streams/{stream_id}: parameters: - $ref: '#/components/parameters/StreamId' - $ref: '#/components/parameters/RegionHeader' get: tags: - Streams summary: Get stream description: > 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. operationId: getStream responses: '200': description: Stream state. headers: X-Overshoot-Region: $ref: '#/components/headers/RegionResponseHeader' content: application/json: schema: $ref: '#/components/schemas/StreamStatusResponse' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Stream unknown, expired, deleted, or owned by a different user. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Wrong region. content: application/json: schema: $ref: '#/components/schemas/RegionError' components: parameters: StreamId: name: stream_id in: path required: true schema: type: string format: uuid description: UUID returned by `POST /streams`. RegionHeader: name: X-Overshoot-Region in: header required: false schema: type: string enum: - us-west1 - us-central1 description: > 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. headers: RegionResponseHeader: description: The region that served this request. schema: type: string enum: - us-west1 - us-central1 schemas: StreamStatusResponse: type: object properties: id: type: string format: uuid state: type: string enum: - active - ended description: > 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: type: number nullable: true description: >- Stream-clock position in ms. Zero until the first frame arrives, then monotonically increasing from that first frame. first_frame_at_ms: type: integer nullable: true description: Wall-clock Unix ms of the first frame ever ingested. last_frame_at_ms: type: integer nullable: true description: Wall-clock Unix ms of the most recent frame. last_frame_index: type: integer nullable: true description: >- Lifetime index of the most recent frame. `frame_index=-1` resolves against this at request time. first_available_frame_at_ms: type: integer nullable: true description: Wall-clock Unix ms of the oldest retained frame. first_available_frame_index: type: integer nullable: true description: Lifetime index of the oldest frame still retained. created_at_ms: type: integer nullable: true description: Wall-clock Unix ms of stream creation. recent_fps: type: number nullable: true description: >- Rolling FPS over the current frame-metrics bucket for active streams. retained_frame_count: type: integer nullable: true evicted_frame_count: type: integer nullable: true expires_at_ms: type: integer nullable: true description: >- Wall-clock Unix ms when the lease will expire. `null` on ended streams. ttl_seconds: type: integer nullable: true ended_at_ms: type: integer nullable: true description: Wall-clock Unix ms when the stream entered the `ended` state. end_reason: type: string nullable: true enum: - expired - deleted description: > Why the stream ended. `expired` = system-driven termination, `deleted` = explicit `DELETE`. `null` while `state == active`. audio: type: boolean default: false description: Reserved for future audio support. Always `false` today. required: - id - state Error: type: object description: Standard error body used by stream-lifecycle and billing endpoints. properties: detail: type: string required: - detail RegionError: type: object description: Returned on `409` when the request reaches the wrong region. properties: detail: type: object properties: error: type: string example: region_error expected_region: type: string example: us-west1 requested_region: type: string nullable: true example: us-central1 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key (e.g. `ovs_...`) description: > Every public HTTP request requires `Authorization: Bearer `, 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. ````