WebSocket Streaming

WebSocket Endpoint

wss://api.retrace.yashbogam.me/ws/v1/stream

For local development: ws://localhost:3001/ws/v1/stream

The WebSocket transport provides the lowest-latency path for streaming trace data. Spans appear in the dashboard within milliseconds of emission, making it ideal for live monitoring and debugging active agent runs.

Authentication

Send an auth message as the first frame after connecting:

{ "type": "auth", "api_key": "rt_live_..." }

The server responds with { "type": "auth_ok" } on success. If authentication fails, the connection closes with code 4001 and a reason string describing the failure.

You must authenticate within 5 seconds of opening the connection or it will be terminated automatically.

Event Types

trace_started

Emitted when a new trace begins recording:

{
  "type": "trace_started",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "research-agent",
    "status": "running",
    "started_at": "2026-01-15T10:00:00Z"
  }
}

span_started

Emitted when a span (LLM call, tool call, or custom step) begins:

{
  "type": "span_started",
  "data": {
    "id": "uuid",
    "trace_id": "uuid",
    "span_type": "llm_call",
    "name": "retrace.ai.generate",
    "model": "gemini-3.1-pro-preview",
    "input": { "messages": [] },
    "started_at": "2026-01-15T10:00:01Z"
  }
}

span_ended

Emitted when a span completes with output, token counts, and cost:

{
  "type": "span_ended",
  "data": {
    "id": "uuid",
    "ended_at": "2026-01-15T10:00:02Z",
    "output": { "content": "..." },
    "output_tokens": 312,
    "cost": 0.004
  }
}

trace_ended

Emitted when the entire trace completes with aggregate metrics:

{
  "type": "trace_ended",
  "data": {
    "id": "uuid",
    "ended_at": "2026-01-15T10:00:05Z",
    "status": "completed",
    "total_tokens": 4891,
    "total_cost": 0.018
  }
}

Heartbeat

The server sends { "type": "ping" } every 30 seconds. Your client must respond with { "type": "pong" } within 30 seconds or the connection will be closed with code 4002.

This mechanism detects stale connections and frees server resources.

Connection Lifecycle

Error Handling

Invalid messages receive an inline error response without closing the connection:

{ "type": "error", "error": "Invalid JSON" }

Repeated invalid messages (more than 10 within 60 seconds) will result in connection termination.

Multiplexing

A single WebSocket connection supports multiple concurrent traces. Every event payload includes a trace_id field so your client can demultiplex events to the correct trace context.

[!NOTE] For serverless environments where persistent connections are impractical, use the HTTP batch transport instead. See the SDK documentation for transport configuration.