> ## 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.

# List persisted voice sessions

> Returns a paginated list of voice sessions stored in the database. Use the status query parameter to filter by session status (active, completed).

Returns a paginated list of voice sessions stored in the database.
Use the `status` query parameter to filter by session status (active, completed).

### Query parameters

<ParamField query="status" type="string">
  Filter by status (active, completed, transferred, failed)
</ParamField>

<ParamField query="search" type="string">
  Case-insensitive search across phone, agent, summary, and transcript
</ParamField>

<ParamField query="started_after" type="string">
  Return only sessions started after the given RFC3339 timestamp
</ParamField>

<ParamField query="sort" type="string">
  Sort by started\_at asc or desc
</ParamField>

<ParamField query="limit" type="integer (int64)">
  Maximum results (default 50, max 200)
</ParamField>

<ParamField query="offset" type="integer (int64)">
  Pagination offset
</ParamField>

### Response

`object`

<ResponseField name="ok" type="boolean" required />

<ResponseField name="tenant" type="string" required>
  Tenant id the listing is scoped to
</ResponseField>

<ResponseField name="sessions" type="object[]" required>
  <Expandable title="sessions">
    <ResponseField name="id" type="string (uuid)" required />

    <ResponseField name="stream_id" type="string" required>
      Media stream id of the session
    </ResponseField>

    <ResponseField name="call_sid" type="string,null" required>
      Twilio call SID, when the session came from a PSTN call
    </ResponseField>

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

    <ResponseField name="customer_phone" type="string,null" required />

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

    <ResponseField name="call_type" type="string,null" required />

    <ResponseField name="status" type="string" required />

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

    <ResponseField name="transcript" type="object" required>
      Transcript JSON as stored (typically an array of turn entries)
    </ResponseField>

    <ResponseField name="rating" type="integer,null" required>
      Caller rating, when collected
    </ResponseField>

    <ResponseField name="sentiment" type="string,null" required />

    <ResponseField name="tags" type="string[]" required />

    <ResponseField name="turn_count" type="integer" required />

    <ResponseField name="started_at" type="string (date-time)" required />

    <ResponseField name="ended_at" type="string,null (date-time)" required />

    <ResponseField name="created_at" type="string (date-time)" required />

    <ResponseField name="updated_at" type="string (date-time)" required />

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

    <ResponseField name="function_call_count" type="integer" required>
      Number of function calls made during the session
    </ResponseField>

    <ResponseField name="transcript_length" type="integer" required>
      Number of transcript entries
    </ResponseField>

    <ResponseField name="metadata" type="object" required />
  </Expandable>
</ResponseField>

<ResponseField name="count" type="integer" required>
  Number of sessions in this page
</ResponseField>

<ResponseField name="filtered_total" type="integer" required>
  Total sessions matching the current filters
</ResponseField>

<ResponseField name="overall_total" type="integer" required>
  Total sessions for the tenant, unfiltered
</ResponseField>

<ResponseField name="status_counts" type="object" required>
  Session counts keyed by status (e.g. active, completed)
</ResponseField>

<ResponseField name="stats" type="object" required>
  <Expandable title="stats">
    <ResponseField name="total" type="integer" required />

    <ResponseField name="average_duration_ms" type="number,null" required />

    <ResponseField name="total_duration_ms" type="integer,null" required />

    <ResponseField name="average_rating" type="number,null" required />
  </Expandable>
</ResponseField>

<ResponseField name="longest_session" type="object,null" required>
  The longest session matching the current filters, in the same shape as `sessions[]` entries; null when there are no sessions
</ResponseField>

### Status codes

| Code  | Meaning                                                                                     |
| ----- | ------------------------------------------------------------------------------------------- |
| `200` | List of voice sessions with filtered/overall totals, per-status counts, and aggregate stats |
| `401` | Unauthorized - invalid or missing bearer token                                              |
| `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' \
    --header "Authorization: Bearer $STATESET_VOICE_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "ok": true,
    "tenant": "acme-outdoors",
    "sessions": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "stream_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "call_sid": "string",
        "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "customer_phone": "+15555555678",
        "agent_name": "string",
        "call_type": "inbound",
        "status": "completed",
        "summary": "Two-person tent, green — replacement for damaged pole set.",
        "transcript": null,
        "rating": 1,
        "sentiment": "string",
        "tags": [],
        "turn_count": 1,
        "started_at": "2026-08-31T14:22:05Z",
        "ended_at": "2026-08-31T14:22:05Z",
        "created_at": "2026-08-31T14:22:05Z",
        "updated_at": "2026-08-31T14:22:05Z",
        "duration_ms": 8,
        "function_call_count": 1,
        "transcript_length": 1,
        "metadata": {}
      }
    ],
    "count": 2,
    "filtered_total": 49,
    "overall_total": 49,
    "status_counts": {},
    "stats": {
      "total": 102,
      "average_duration_ms": 7.5,
      "total_duration_ms": 8,
      "average_rating": 1.5
    },
    "longest_session": {}
  }
  ```
</ResponseExample>