> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Look up a voice session by Twilio stream ID

> Returns the full voice session record matching the given Twilio stream ID. Useful for correlating Twilio webhook data back to session records.

Returns the full voice session record matching the given Twilio stream ID.
Useful for correlating Twilio webhook data back to session records.

### Path parameters

<ParamField path="stream_id" type="string" required>
  Twilio stream ID (e.g. MZ1234...)
</ParamField>

### Response

`VoiceSession`

<ResponseField name="agent_name" type="string,null">
  AI agent name
</ResponseField>

<ResponseField name="call_sid" type="string,null">
  Twilio call SID
</ResponseField>

<ResponseField name="call_type" type="string,null">
  Type of call: inbound, outbound, sip\_inbound
</ResponseField>

<ResponseField name="created_at" type="string" required>
  Record creation time (ISO 8601)
</ResponseField>

<ResponseField name="customer_phone" type="string,null">
  Customer phone number (E.164)
</ResponseField>

<ResponseField name="duration_ms" type="integer,null (int64)">
  Session duration in milliseconds
</ResponseField>

<ResponseField name="ended_at" type="string" required>
  Session end time (ISO 8601)
</ResponseField>

<ResponseField name="function_calls" type="object" required>
  Function calls made during the session as JSON array
</ResponseField>

<ResponseField name="id" type="string" required>
  Unique session identifier
</ResponseField>

<ResponseField name="metadata" type="object" required>
  Arbitrary session metadata
</ResponseField>

<ResponseField name="model" type="string,null">
  AI model used
</ResponseField>

<ResponseField name="org_id" type="string,null">
  Organization ID
</ResponseField>

<ResponseField name="rating" type="integer,null (int32)">
  Operator-provided review rating
</ResponseField>

<ResponseField name="sentiment" type="string,null">
  Operator or model sentiment label
</ResponseField>

<ResponseField name="started_at" type="string" required>
  Session start time (ISO 8601)
</ResponseField>

<ResponseField name="status" type="string" required>
  Session status: active, completed
</ResponseField>

<ResponseField name="stream_id" type="string" required>
  Twilio stream ID
</ResponseField>

<ResponseField name="summary" type="string,null">
  LLM-generated summary
</ResponseField>

<ResponseField name="tags" type="string[]" required>
  Session tags applied in the voice desk
</ResponseField>

<ResponseField name="tenant_id" type="string" required>
  Tenant that owns this session
</ResponseField>

<ResponseField name="transcript" type="object" required>
  Conversation transcript as JSON array
</ResponseField>

<ResponseField name="turn_count" type="integer (int32)" required>
  Number of conversation turns
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  Record last updated time (ISO 8601)
</ResponseField>

<ResponseField name="vad_events" type="object" required>
  Voice activity detection events as JSON array
</ResponseField>

<ResponseField name="voice" type="string,null">
  TTS voice used
</ResponseField>

### Status codes

| Code  | Meaning                                        |
| ----- | ---------------------------------------------- |
| `200` | Voice session detail                           |
| `401` | Unauthorized - invalid or missing bearer token |
| `404` | Voice session not found for given stream ID    |
| `500` | Internal server error                          |
| `503` | Database not configured - set DATABASE\_URL    |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.voice.stateset.com/api/v1/voice-sessions/by-stream/{stream_id}' \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "agent_name": "ResponseCX",
    "call_sid": "CA1234567890abcdef1234567890abcdef",
    "call_type": "inbound",
    "created_at": "2024-01-15T10:30:00Z",
    "customer_phone": "+15555555678",
    "duration_ms": 142000,
    "ended_at": "2024-01-15T10:32:22Z",
    "function_calls": null,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "metadata": null,
    "model": "gpt-4o-realtime-preview",
    "org_id": "org-456",
    "rating": 4,
    "sentiment": "positive",
    "started_at": "2024-01-15T10:30:00Z",
    "status": "completed",
    "stream_id": "MZ1234567890abcdef1234567890abcdef",
    "summary": "Customer inquired about order ORD-123 status. Agent confirmed it shipped yesterday.",
    "tags": [
      "vip",
      "escalation"
    ],
    "tenant_id": "tenant-123",
    "transcript": null,
    "turn_count": 12,
    "updated_at": "2024-01-15T10:32:22Z",
    "vad_events": null,
    "voice": "alloy"
  }
  ```
</ResponseExample>