streams

End a stream (idempotent)

Graceful end: settles the credit reservation for the billed live-clock seconds (releases it entirely when the stream never went live). Ending an already-ended stream returns the terminal resource unchanged.

post/v1/streams/{id}/end

Request

  • Base URL: https://api.primateintelligence.ai
  • URL: https://api.primateintelligence.ai/v1/streams/{id}/end
  • Auth: HTTP bearer

Path parameters

idstring required

Response

The ended stream with final usage.

idstring required

Stream resource id (prefixed ULID). P6 §4.8.

object'stream' required
status'queued' | 'ready' | 'live' | 'ended' required

Stream lifecycle state (§4.8): queued → ready → live → ended. Terminal immutable.

metering_rule'per_second' | 'per_frame'

PRI-552: settlement rule pinned at create time. Streams created before the cutover report per_second.

end_reason'completed' | 'canceled' | 'insufficient_credits' | 'error' | 'timeout' | 'ice_failed' | 'media_timeout' nullable required

Why the stream ended. completed — normal end after live. canceled — ended before going live (client action). insufficient_credits — balance exhausted. error — server-side failure. timeout — max_session_s cutoff. ice_failed — WebRTC ICE never connected (see failure_diagnostic). media_timeout — connected but no media/results within the first-frame window. A stream that never went live is never completed.

promptstring nullable required
queryobject nullable required
modelstring required
queue_positioninteger nullable required
estimated_start_sinteger nullable required
ice_serversobject[] nullable required
duration_sinteger nullable required

Live-clock duration. Terminal only.

results_summaryobject nullable required

Terminal summary: {result_frames, frames (deprecated alias of result_frames — removed ~2026-08-28), last_detections}. result_frames counts result EVENTS emitted (results are sampled, not per-source-frame). Detection rows use the same enums/casing as the file-API result contract (answer: yes|no|indeterminate, lowercase; prompt echoed exactly as submitted).

failure_diagnosticobject nullable required

Present when end_reason is ice_failed (and some media_timeout cases): ICE candidate summary from the server side — {local_candidates: string[], hint}. Use it to distinguish "server advertised only private/host candidates" from "client could not reach relay".

metadataobject

Free-form key/value metadata. ≤16 keys, key ≤40 chars [a-zA-Z0-9_.-], value ≤500 chars.

created_atstring date-time required
live_started_atstring date-time nullable required
ended_atstring date-time nullable required

Example response

{
  "id": "st_01KX12XX3BNM688AWHX7406HCF",
  "model": "Darwin-preview-1.3B",
  "signaling": {
    "url": "wss://api.primateintelligence.ai/v1/streams/st_01KX…/signal",
    "expires_at": "2026-07-08T14:00:00Z"
  },
  "created_at": "2026-07-08T14:00:00Z",
  "live_started_at": "2026-07-08T14:00:00Z",
  "ended_at": "2026-07-08T14:00:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.