Get session status

Canonical V0 status endpoint (Decision D1). Returns the current session state. NEVER includes client_token; use POST /v1/sessions/{session_id}/client-token to refresh the token.

The legacy /v1/sessions/{session_id}/status path is retained on the deployed Worker as a bridge/internal alias but is NOT canonical V0.

GET/v1/sessions/{session_id}

Authorization

AuthorizationBearer token · headerrequired

`Authorization: Bearer <api_key>`

x-api-keyAPI key · headerrequired

`x-api-key: <api_key>`

Path parameters

session_idstringrequired

min length 1 · matches ^session:[A-Za-z0-9_-]+$

Responses

200Current session status. Does NOT include `client_token`.

created_atinteger<int64>

Unix epoch milliseconds.

min 0

ended_atinteger<int64>

Unix epoch milliseconds.

min 0

provider_typestringrequired

Provider type selected at session creation (e.g. `openai_realtime`). Derived from sanitized `config.provider_type`; NEVER reflects raw `provider_config` credentials.

session_idstringrequired

Session identifier (always prefixed with `session:`).

min length 1 · matches ^session:[A-Za-z0-9_-]+$

started_atinteger<int64>

Unix epoch milliseconds.

min 0

statusstringrequired

Session lifecycle status.

Allowed:createdactivatingactiveendingendedended_with_warningsfailed

transportstringrequired

Transport preference for this session. `auto` — server picks (prefers SFU when configured, falls back to fMP4). `webrtc_sfu` — Cloudflare Realtime SFU (WebRTC); fails closed if the SFU prerequisites are missing, does NOT fall back to fMP4. `websocket_fmp4` — fMP4 over WebSocket (compatibility transport).

Allowed:autowebrtc_sfuwebsocket_fmp4

401API key missing or invalid.

Any of:

object

codestringrequired

Allowed:AVTR_PROVIDER_DOWNSTREAM_FAILEDAVTR_PROVIDER_TIMEOUTAVTR_PROVIDER_UNAVAILABLEAVTR_RATE_LIMIT_CONCURRENT_SESSIONSAVTR_RATE_LIMIT_EXCEEDEDAVTR_RATE_LIMIT_PROVIDER_QUOTAAVTR_RENDER_CAPACITYAVTR_RENDER_TIMEOUTAVTR_SESSION_STATE_UNAVAILABLEAVTR_SFU_CONNECTION_FAILEDAVTR_SFU_NEGOTIATION_FAILEDAVTR_SFU_ROOM_FULL

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

Allowed:AVTR_AUTH_EXPIRED_TOKENAVTR_AUTH_FORBIDDENAVTR_AUTH_INVALID_KEYAVTR_AUTH_MISSING_CREDENTIALSAVTR_AUTH_MISSING_SCOPEAVTR_PROVIDER_MISCONFIGUREDAVTR_RENDER_FAILEDAVTR_RENDER_MISCONFIGUREDAVTR_SESSION_CANCELLEDAVTR_SESSION_CONFLICTAVTR_SESSION_ENDEDAVTR_SESSION_NOT_FOUNDAVTR_SFU_NOT_CONFIGURED

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

403Missing `sessions:read` scope.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

404Session not found, or cross-tenant access denied (returns 404 to avoid resource enumeration).

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

429Rate limit exceeded.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

503Session state temporarily unavailable.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

session_idpath*

Request

curl -X GET "https://api.avtr.internal/v1/v1/sessions/session%3A02732348-1350-413a-9f0c-d6f47210b417" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://api.avtr.internal/v1/v1/sessions/session%3A02732348-1350-413a-9f0c-d6f47210b417", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.get(
    "https://api.avtr.internal/v1/v1/sessions/session%3A02732348-1350-413a-9f0c-d6f47210b417",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

{
  "created_at": 0,
  "ended_at": 0,
  "provider_type": "string",
  "session_id": "session:02732348-1350-413a-9f0c-d6f47210b417",
  "started_at": 0,
  "status": "created",
  "transport": "auto"
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}