# The partner's connection log, newest first

> GET /v1/sessions: The partner's connection log, newest first.

Source: https://docs.voice.kheelona.com/reference/generated/api/listsessions/

`GET /v1/sessions`

| Property | Value |
| --- | --- |
| Operation | `listSessions` |
| Scope | `sessions:read` |

## Parameters

| Name | In | Type | Required | Description | Rules |
| --- | --- | --- | --- | --- | --- |
| `from` | query | string | no | Created at or after (RFC 3339); default: `to` − 31 days. | format `date-time` |
| `to` | query | string | no | Created before (RFC 3339); default: now (plus a 5-minute clock-skew margin). At most 31 days after `from`. | format `date-time` |
| `voice_id` | query | string | no | Only this voice. |  |
| `status` | query | string | no | Only this status. | one of `reserved`, `live`, `ended`, `expired`, `rejected`, `error` |
| `end_reason` | query | string | no | Only sessions that ended for this reason. | one of `client_ended`, `partner_ended`, `max_duration`, `idle_timeout`, `disconnected`, `server_shutdown`, `server_lost`, `provider_failure`, `suspended`, `service_stopped`, `error` |
| `end_user_ref` | query | string | no | Only this end user. |  |
| `api_key_id` | query | string | no | Only sessions created by this key. |  |
| `limit` | query | integer | no | Rows per page, 1–100 (default 25). | format `int32`; min 1; max 100; default `25` |
| `cursor` | query | string | no | `next_cursor` from the previous page; absent for the first page. |  |

## Responses

### 200

A page of sessions, newest first

| Header | Type | Description |
| --- | --- | --- |
| `RateLimit-Limit` | integer | Requests allowed at once for this key |
| `RateLimit-Remaining` | integer | Requests left right now |
| `RateLimit-Reset` | integer | Seconds until the limit is full again |
| `X-Request-Id` | string | The request's ID (`req_…`); quote it in reports. |

| Field | Type | Required | Description | Rules |
| --- | --- | --- | --- | --- |
| `data` | array of object | yes | The rows, in the list's order (newest first, except the members lists, which are oldest first). |  |
| `data[].id` | string | yes | `ses_…` |  |
| `data[].status` | string | yes | Lifecycle state. A session's lifecycle state. | one of `reserved`, `live`, `ended`, `expired`, `rejected`, `error` |
| `data[].voice` | object | yes | The voice and its pinned version. |  |
| `data[].voice.id` | string | yes | The voice ID. |  |
| `data[].voice.version` | integer | no | The pinned version. | format `int32`; may be null |
| `data[].languages` | array of string | yes | The declared languages. |  |
| `data[].client` | object | yes | Where the client connected from. |  |
| `data[].client.kind` | string | yes | Who connected. `browser`: your web page, through the SDK; `server`: your server or device relay; `playground`: a session started from your console's playground; `admin`: a Kheelona support or test session (internal tools). | one of `browser`, `server`, `playground`, `admin` |
| `data[].client.ip` | string | no | The client's IP; a network (`203.0.113.0/24`) after 30 days. | may be null |
| `data[].client.region` | string | no | ISO 3166-2 region of the IP, e.g. `IN-KA`, looked up offline (country and region only, never an exact location). Region codes are recorded for India only for now; absent for any other country, and when the address is private. | may be null |
| `data[].client.transport` | string | no | How (once connected). How the client connected. | one of `webrtc`, `websocket`; may be null |
| `data[].client.user_agent` | string | no | The client's user agent. | may be null |
| `data[].created_at` | string | yes | Created. | format `date-time` |
| `data[].turns` | integer | yes | Turns. | format `int32` |
| `data[].interruptions` | integer | yes | Barge-ins. | format `int32` |
| `data[].languages_heard` | array of string | yes | Languages the person spoke. |  |
| `data[].latency` | object | yes | Latency percentiles. |  |
| `data[].latency.v2v_p50_ms` | integer | no | Median end-of-speech → first reply audio. | format `int32`; may be null |
| `data[].latency.v2v_p95_ms` | integer | no | 95th percentile. | format `int32`; may be null |
| `data[].audio` | object | yes | Audio totals. |  |
| `data[].audio.user_speech_ms` | integer | yes | The person's speech. | format `int32` |
| `data[].audio.reply_audio_ms` | integer | yes | The voice's audio. | format `int32` |
| `data[].tokens` | object | yes | Reply model tokens. |  |
| `data[].tokens.input` | integer | yes | Input tokens. | format `int32` |
| `data[].tokens.output` | integer | yes | Output tokens. | format `int32` |
| `data[].tokens.thinking` | integer | yes | Thinking tokens. | format `int32` |
| `data[].safety` | object | yes | Safety interventions. |  |
| `data[].safety.input` | integer | yes | The person's speech blocked. | format `int64`; min 0 |
| `data[].safety.output` | integer | yes | A reply blocked. | format `int64`; min 0 |
| `data[].safety.provider` | integer | yes | Blocked by the model provider. | format `int64`; min 0 |
| `data[].errors` | object | yes | Error counts by error code. |  |
| `data[].api_key_id` | string | no | The key that created it. | may be null |
| `data[].connected_at` | string | no | Reached `session.ready`. | format `date-time`; may be null |
| `data[].duration_ms` | integer | no | Connected time. | format `int32`; may be null |
| `data[].end_reason` | string | no | Why it ended, e.g. `client_ended`, `partner_ended`, `idle_timeout`. | may be null |
| `data[].end_user_ref` | string | no | Your opaque user reference. | may be null |
| `data[].ended_at` | string | no | Ended. | format `date-time`; may be null |
| `data[].metadata` | object | no | Your metadata. | may be null |
| `data[].reject_reason` | string | no | Why admission refused it (`status = rejected`): `partner_limit_reached`, `capacity_exhausted`, … | may be null |
| `next_cursor` | string | no | Pass as `cursor` to get the next page; `null` at the end. | may be null |

### 400

Invalid filter or cursor

| Header | Type | Description |
| --- | --- | --- |
| `RateLimit-Limit` | integer | Requests allowed at once for this key |
| `RateLimit-Remaining` | integer | Requests left right now |
| `RateLimit-Reset` | integer | Seconds until the limit is full again |
| `X-Request-Id` | string | The request's ID (`req_…`); quote it in reports. |

| Field | Type | Required | Description | Rules |
| --- | --- | --- | --- | --- |
| `error` | object | yes | The error. |  |
| `error.code` | string | yes |  | one of `invalid_request`, `unauthenticated`, `secret_expired`, `forbidden`, `origin_not_allowed`, `voice_not_found`, `session_not_found`, `capacity_exhausted`, `partner_limit_reached`, `rate_limited`, `internal`, `not_found`, `conflict`, `unavailable` |
| `error.message` | string | yes | A short, fixed description. Never quotes the request. |  |
| `error.request_id` | string | yes | The request's ID (also in the `X-Request-Id` header); quote it when reporting a problem. | pattern `^req_[0-9A-HJKMNP-TV-Z]{26}$` |
| `error.details` | any | no | Structured detail, e.g. `{"field": "languages[1]"}` or `{"reason": "quota_exhausted"}`. |  |

### 401

Missing or invalid API key

| Header | Type | Description |
| --- | --- | --- |
| `RateLimit-Limit` | integer | Requests allowed at once for this key |
| `RateLimit-Remaining` | integer | Requests left right now |
| `RateLimit-Reset` | integer | Seconds until the limit is full again |
| `X-Request-Id` | string | The request's ID (`req_…`); quote it in reports. |

| Field | Type | Required | Description | Rules |
| --- | --- | --- | --- | --- |
| `error` | object | yes | The error. |  |
| `error.code` | string | yes |  | one of `invalid_request`, `unauthenticated`, `secret_expired`, `forbidden`, `origin_not_allowed`, `voice_not_found`, `session_not_found`, `capacity_exhausted`, `partner_limit_reached`, `rate_limited`, `internal`, `not_found`, `conflict`, `unavailable` |
| `error.message` | string | yes | A short, fixed description. Never quotes the request. |  |
| `error.request_id` | string | yes | The request's ID (also in the `X-Request-Id` header); quote it when reporting a problem. | pattern `^req_[0-9A-HJKMNP-TV-Z]{26}$` |
| `error.details` | any | no | Structured detail, e.g. `{"field": "languages[1]"}` or `{"reason": "quota_exhausted"}`. |  |

### 403

The key lacks `sessions:read`

| Header | Type | Description |
| --- | --- | --- |
| `RateLimit-Limit` | integer | Requests allowed at once for this key |
| `RateLimit-Remaining` | integer | Requests left right now |
| `RateLimit-Reset` | integer | Seconds until the limit is full again |
| `X-Request-Id` | string | The request's ID (`req_…`); quote it in reports. |

| Field | Type | Required | Description | Rules |
| --- | --- | --- | --- | --- |
| `error` | object | yes | The error. |  |
| `error.code` | string | yes |  | one of `invalid_request`, `unauthenticated`, `secret_expired`, `forbidden`, `origin_not_allowed`, `voice_not_found`, `session_not_found`, `capacity_exhausted`, `partner_limit_reached`, `rate_limited`, `internal`, `not_found`, `conflict`, `unavailable` |
| `error.message` | string | yes | A short, fixed description. Never quotes the request. |  |
| `error.request_id` | string | yes | The request's ID (also in the `X-Request-Id` header); quote it when reporting a problem. | pattern `^req_[0-9A-HJKMNP-TV-Z]{26}$` |
| `error.details` | any | no | Structured detail, e.g. `{"field": "languages[1]"}` or `{"reason": "quota_exhausted"}`. |  |

### 429

Rate limited

| Header | Type | Description |
| --- | --- | --- |
| `RateLimit-Limit` | integer | Requests allowed at once for this key |
| `RateLimit-Remaining` | integer | Requests left right now |
| `RateLimit-Reset` | integer | Seconds until the limit is full again |
| `Retry-After` | integer | Seconds to wait before retrying |
| `X-Request-Id` | string | The request's ID (`req_…`); quote it in reports. |

| Field | Type | Required | Description | Rules |
| --- | --- | --- | --- | --- |
| `error` | object | yes | The error. |  |
| `error.code` | string | yes |  | one of `invalid_request`, `unauthenticated`, `secret_expired`, `forbidden`, `origin_not_allowed`, `voice_not_found`, `session_not_found`, `capacity_exhausted`, `partner_limit_reached`, `rate_limited`, `internal`, `not_found`, `conflict`, `unavailable` |
| `error.message` | string | yes | A short, fixed description. Never quotes the request. |  |
| `error.request_id` | string | yes | The request's ID (also in the `X-Request-Id` header); quote it when reporting a problem. | pattern `^req_[0-9A-HJKMNP-TV-Z]{26}$` |
| `error.details` | any | no | Structured detail, e.g. `{"field": "languages[1]"}` or `{"reason": "quota_exhausted"}`. |  |