One of the partner's sessions
GET /v1/sessions/{id}
| Property | Value |
|---|---|
| Operation | getSession |
| Scope | sessions:read |
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description | Rules |
|---|---|---|---|---|---|
id |
path | string | yes | The session ID (ses_…) |
Responses
Section titled “Responses”The session (metadata and summary metrics, no content)
| 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 |
|---|---|---|---|---|
id |
string | yes | ses_… |
|
status |
string | yes | Lifecycle state. A session’s lifecycle state. | one of reserved, live, ended, expired, rejected, error |
voice |
object | yes | The voice and its pinned version. | |
voice.id |
string | yes | The voice ID. | |
voice.version |
integer | no | The pinned version. | format int32; may be null |
languages |
array of string | yes | The declared languages. | |
client |
object | yes | Where the client connected from. | |
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 |
client.ip |
string | no | The client’s IP; a network (203.0.113.0/24) after 30 days. |
may be null |
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 |
client.transport |
string | no | How (once connected). How the client connected. | one of webrtc, websocket; may be null |
client.user_agent |
string | no | The client’s user agent. | may be null |
created_at |
string | yes | Created. | format date-time |
turns |
integer | yes | Turns. | format int32 |
interruptions |
integer | yes | Barge-ins. | format int32 |
languages_heard |
array of string | yes | Languages the person spoke. | |
latency |
object | yes | Latency percentiles. | |
latency.v2v_p50_ms |
integer | no | Median end-of-speech → first reply audio. | format int32; may be null |
latency.v2v_p95_ms |
integer | no | 95th percentile. | format int32; may be null |
audio |
object | yes | Audio totals. | |
audio.user_speech_ms |
integer | yes | The person’s speech. | format int32 |
audio.reply_audio_ms |
integer | yes | The voice’s audio. | format int32 |
tokens |
object | yes | Reply model tokens. | |
tokens.input |
integer | yes | Input tokens. | format int32 |
tokens.output |
integer | yes | Output tokens. | format int32 |
tokens.thinking |
integer | yes | Thinking tokens. | format int32 |
safety |
object | yes | Safety interventions. | |
safety.input |
integer | yes | The person’s speech blocked. | format int64; min 0 |
safety.output |
integer | yes | A reply blocked. | format int64; min 0 |
safety.provider |
integer | yes | Blocked by the model provider. | format int64; min 0 |
errors |
object | yes | Error counts by error code. | |
api_key_id |
string | no | The key that created it. | may be null |
connected_at |
string | no | Reached session.ready. |
format date-time; may be null |
duration_ms |
integer | no | Connected time. | format int32; may be null |
end_reason |
string | no | Why it ended, e.g. client_ended, partner_ended, idle_timeout. |
may be null |
end_user_ref |
string | no | Your opaque user reference. | may be null |
ended_at |
string | no | Ended. | format date-time; may be null |
metadata |
object | no | Your metadata. | may be null |
reject_reason |
string | no | Why admission refused it (status = rejected): partner_limit_reached, capacity_exhausted, … |
may be null |
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"}. |
session_not_found
| 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"}. |