Observability API

Monitor session quality, trace conversations, and debug issues.

List Sessions

GET /v1/observability/sessions

Query Parameters

Param	Type	Description
agentId	string	Filter by agent
limit	number	Max results (default 20)
cursor	string	Pagination cursor

Response 200

{
  "data": [
    {
      "id": "sess_abc123",
      "agentId": "agent_xyz",
      "startedAt": "2026-03-21T10:00:00Z",
      "endedAt": "2026-03-21T10:05:30Z",
      "turns": 12,
      "status": "completed"
    }
  ],
  "nextCursor": "sess_xyz",
  "hasMore": true
}

Get Session Detail

GET /v1/observability/sessions/:sessionId

Returns full session trace including per-turn metrics, tool executions, and timing data.

Response 200

{
  "id": "sess_abc123",
  "agentId": "agent_xyz",
  "turns": [
    {
      "index": 0,
      "speaker": "agent",
      "text": "Hello! How can I help?",
      "startMs": 0,
      "endMs": 1200,
      "sttMs": 0,
      "llmMs": 450,
      "ttsMs": 380
    }
  ],
  "metrics": {
    "totalDurationMs": 330000,
    "avgTurnLatencyMs": 850,
    "toolExecutions": 3
  }
}

Root Cause Analysis

Automated analysis of session issues (high latency, failed turns, quality problems).

GET /v1/observability/sessions/:sessionId/root-cause

Response 200

{
  "sessionId": "sess_abc123",
  "issues": [
    {
      "type": "high_latency",
      "turn": 5,
      "description": "TTS latency spike to 2.3s (target: <900ms)",
      "recommendation": "Consider switching to Cartesia for lower TTFB"
    }
  ]
}

Interruption Quality

Aggregate interruption quality metrics across sessions.

GET /v1/observability/sessions/interruption-quality

Returns detection latency, stop latency, and bleed-through word counts. Used as release-gate signals for voice UX quality.

Call Observability

GET /v1/observability/calls/:callId
GET /v1/observability/calls/:callId/root-cause

Call-level equivalents of session observability, keyed by Twilio call SID.

Recordings

GET /v1/recordings/:callId

Retrieve the recording for a completed call.