The partner's connection log, newest first
GET /v1/sessions
| Property | Value |
|---|---|
| Operation | listSessions |
| Scope | sessions:read |
Parameters
Section titled “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
Section titled “Responses”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 |
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"}. |
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"}. |
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"}. |
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"}. |