> ## 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.

# Stream info

> Get real-time information about an active stream, including perceived FPS, resolution, and inference statistics.

<Warning>
  The v0.2 API is deprecated. New integrations should use v1.
</Warning>


## OpenAPI

````yaml api-reference/v0.2/openapi.json GET /streams/{stream_id}/info
openapi: 3.1.0
info:
  title: Overshoot Streaming API
  description: >-
    Real-time video and image inference API. Stream video from any source
    (camera, file, RTSP, screen share) and receive continuous AI analysis
    results over WebSocket.


    ## Quick start


    1. **Create a stream** — `POST /streams` with a prompt and model

    2. **Connect WebSocket** — `WS /ws/streams/{stream_id}` to receive results

    3. **Send keepalives** — `POST /streams/{stream_id}/keepalive` every 15s

    4. **Close when done** — `DELETE /streams/{stream_id}`


    ## List models


    `GET /models` returns available models and their current status.


    ```json

    [{"model": "Qwen/Qwen3.5-9B", "ready": true, "status": "ready"}]

    ```


    | Status | `ready` | Meaning |

    |--------|---------|----------|

    | `ready` | `true` | Healthy, performing well |

    | `degraded` | `true` | Near capacity, higher latency expected |

    | `saturated` | `false` | At capacity, will reject new streams |

    | `unavailable` | `false` | Endpoint not reachable |


    ## WebSocket — Receive results


    Connect to `WS /ws/streams/{stream_id}` to receive inference results in
    real-time.


    **Authentication:** Send your API key as the first message:

    ```json

    {"api_key": "your-api-key"}

    ```


    **Result messages:** Each message is a `StreamInferenceResult` with fields:
    `result` (model output), `ok`, `error`, `finish_reason`,
    `inference_latency_ms`, `total_latency_ms`.


    **Close codes:**

    - `1008` — Authentication failed

    - `1001` — Stream ended (reasons: `client_requested`, `lease_expired`,
    `insufficient_credits`, transport disconnected)


    ## Authentication


    All endpoints require a Bearer token: `Authorization: Bearer <api_key>`


    Get your API key at
    [platform.overshoot.ai](https://platform.overshoot.ai/api-keys).


    ## SDKs


    - **JavaScript:** `npm install overshoot`

    - **Python:** `pip install
    git+https://github.com/Overshoot-ai/overshoot-python.git`


    Full documentation at [docs.overshoot.ai](https://docs.overshoot.ai).
  version: '0.2'
servers:
  - url: /v0.2
security: []
tags:
  - name: streams
    description: Create, manage, and close video inference streams.
  - name: internal
    description: Internal/experimental endpoints. Not used by SDKs.
paths:
  /streams/{stream_id}/info:
    get:
      tags:
        - streams
      summary: Stream info
      description: >-
        Get real-time information about an active stream, including perceived
        FPS, resolution, and inference statistics.
      operationId: stream_info_streams__stream_id__info_get
      parameters:
        - name: stream_id
          in: path
          required: true
          schema:
            type: string
            title: Stream Id
      responses:
        '200':
          description: Stream info retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamInfoResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Stream not found or not owned by this API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - API Key: []
components:
  schemas:
    StreamInfoResponse:
      properties:
        stream_id:
          type: string
          title: Stream Id
          description: Stream identifier
        source_type:
          type: string
          title: Source Type
          description: 'Transport type: native, webrtc, or livekit'
        state:
          type: string
          enum:
            - pending
            - active
            - idle
          title: State
          description: >-
            Current stream state: pending (no frames yet), active (inferencing),
            idle (frames stopped)
        uptime_seconds:
          type: number
          title: Uptime Seconds
          description: Seconds since stream was created
        fps:
          type: number
          title: Fps
          description: Perceived frames per second (measured over last metrics interval)
        frame_width:
          type: integer
          title: Frame Width
          description: Original video frame width in pixels
        frame_height:
          type: integer
          title: Frame Height
          description: Original video frame height in pixels
        effective_width:
          type: integer
          title: Effective Width
          description: Processing width after 720p cap
        effective_height:
          type: integer
          title: Effective Height
          description: Processing height after 720p cap
        inferences_completed:
          type: integer
          title: Inferences Completed
          description: Total successful inferences since stream start
        inferences_failed:
          type: integer
          title: Inferences Failed
          description: Total failed inferences since stream start
        last_inference_latency_seconds:
          type: number
          title: Last Inference Latency Seconds
          description: Latency of the most recent inference (seconds)
      type: object
      required:
        - stream_id
        - source_type
        - state
        - uptime_seconds
        - fps
        - frame_width
        - frame_height
        - effective_width
        - effective_height
        - inferences_completed
        - inferences_failed
        - last_inference_latency_seconds
      title: StreamInfoResponse
      description: Real-time information about a connected stream.
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
        details:
          anyOf:
            - {}
            - type: 'null'
          title: Details
      type: object
      required:
        - error
      title: ErrorResponse
      description: Error response.
  securitySchemes:
    API Key:
      type: http
      description: Provide your API key in the Authorization header as 'Bearer <api_key>'
      scheme: bearer

````