Open the events channel of a Call
GET /v1/calls/{call_id}/stream
| Property | Value |
|---|---|
| Operation | stream_call |
| Group | Calls |
| Scope | calls:write |
Scopes of include values | tool_calls needs calls:write; transcripts needs transcripts:read |
| Route class | read |
| Idempotency | No Idempotency-Key |
| Audit | An audited content read call.stream.open, when the request names an include value |
| Released in | 1.49.0 |
| Phase 0 host | Served (the hosted api pins 1.65.0) |
Upgrades to a WebSocket that carries the Call's events as they happen and accepts control commands and function Tool results (FR-calls-11). Every server message is a StreamServerMessage with the Session's seq; reconnect with after_seq to resume within the retained window (the last 1,000 messages, kept until 10 minutes after the Call ends; targets), or read resume_gap and then GET /v1/calls/{call_id}/events. A client sends StreamClientMessage values. include=transcripts adds the transcript messages and needs transcripts:read; include=tool_calls makes the connection a function Tool handler, which receives tool.invoked with the arguments, and while no such connection is open a function Tool returns no_handler (FR-orchestration-10). Naming either makes opening the connection an audited content read. Up to three connections per Call (a target); a fourth answers 429 stream_limit_reached. A Call that has ended past the retained window answers 409 call_not_active. The JSON Schemas of both message unions ship beside the OpenAPI documents as stream.server.schema.json and stream.client.schema.json.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
call_id | path | CallId | yes | The id of a Call: call_ and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log. |
after_seq | query | integer | no | Resume after this seq; the server replays the retained messages after it, or sends resume_gap. |
partials | query | one of "true", "false" | no | true adds transcript.partial to a connection with include=transcripts. |
include | query | array of StreamInclude | no | Content classes to add, comma-separated. Naming any makes opening the connection an audited content read. |
Responses
| Status | Content type | Shape | Error codes |
|---|---|---|---|
101 | |||
400 | application/json | ErrorEnvelope | invalid_request |
401 | application/json | ErrorEnvelope | unauthenticated |
403 | application/json | ErrorEnvelope | forbidden |
404 | application/json | ErrorEnvelope | not_found |
409 | application/json | ErrorEnvelope | call_not_active |
429 | application/json | ErrorEnvelope | stream_limit_reached, rate_limited |
500 | application/json | ErrorEnvelope | internal_error |
WebSocket messages
The request upgrades to a WebSocket (status 101). The server sends StreamServerMessage and the client sends StreamClientMessage; their JSON Schemas ship in the contracts release as stream.client.schema.json and stream.server.schema.json.