---
title: "List billed realtime sessions"
method: GET
path: "/v1/usage/sessions"
tags: ["Usage"]
---

# List billed realtime sessions

`GET /v1/usage/sessions`

## Request

- Base URL: `https://realtimeavatar.ai/api`
- URL: `https://realtimeavatar.ai/api/v1/usage/sessions`
- Auth: HTTP bearer

Per-second billable detail. The window defaults to the trailing 30 days and is CLAMPED to 90 — a wider range is served narrowed, not refused, so read back the returned from/to.

Requires an API key with the `usage:read` scope.

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `limit` integer
- `cursor` string
- `endUserId` string

## Headers

- `X-RTA-Release-Evidence` '1'
- `X-RTA-Speech-Diagnostics` '1'

## Response `200`

Sessions

- ListUsageSessionsResponse
  - `data` object[], required
    - `sessionId` string, required
    - `speechDiagnostics` union: Only returned for X-RTA-Speech-Diagnostics: 1. Closed dialogue record, whole-session cohort, not sliced to query dates or pooled across turns. Missing legs remain absent. Opt-in pages cap at 50; 65536 bytes per summary, 5000 ms total page deadline, concurrency 4. Unavailable evidence is explicit, never zero.
      - object
        - `latency_ms` object, required
        - `status` 'available', required
        - `sourceRole` 'dialogue', required
        - `coverage` object, required
          - `first_at` string, nullable, required
          - `last_at` string, nullable, required
          - `lines` integer, required
      - object
        - `status` 'unavailable', required
        - `reason` 'not_closed' | 'unconfigured' | 'missing' | 'invalid' | 'oversized' | 'unscorable' | 'no_measured_latency' | 'timeout' | 'aborted' | 'storage_unavailable', required
    - `releaseIdentity` object: Returned only for X-RTA-Release-Evidence: 1. Omitted by default for strict client compatibility. Evidence is stored against this session; missing evidence remains null.
      - `deploymentId` string, nullable, required
      - `workerRevision` string, nullable, required
      - `provenance` object, required
        - `deploymentSource` 'cloudflare-worker-version', required
        - `workerSource` 'authenticated-worker-heartbeat', nullable, required
        - `workerId` string, nullable, required
        - `podStartedAtMs` integer, nullable, required
        - `workerObservedAt` string, date-time, nullable, required
    - `avatarId` string, nullable, required
    - `avatarName` string, nullable, required
    - `status` 'reserved' | 'started' | 'released' | 'failed', required
    - `startedAt` string, nullable, required
    - `endedAt` string, nullable, required
    - `activeSeconds` number, nullable, required
    - `billedCreditMicros` integer, nullable, required
    - `metadata` object, required
    - `createdAt` string, required
  - `nextCursor` string, nullable, required
  - `from` string, date-time, required
  - `to` string, date-time, required

## Other responses

- `401`: Missing, malformed, revoked, or expired key.
- `403`: The key lacks the scope for this operation, or the tenant is not active.
- `default`: Error. Route-dependent: 400 (a field this route cannot honour — see `portraitUrl` on `UpdateAvatarRequest`), 402 (insufficient credits or spend limit), 404 (no such avatar, voice, or key for this tenant — the message often reads "does not belong to this tenant", which is a missing id and not a permission failure), 408 (the request was cancelled), 409 (the resource is not in a state that accepts this write — a stale `expectedRevision`, a render already in flight, or a mint that asked for a clip library still building), 411 (`POST /v1/assets/remote` only — the origin serving `remoteUrl` sent no `content-length`, so the platform will not stream it), 422 (strict schema rejection, or a motion description the safety screen refused), 429 (rate limited), 502 (upstream render failed), 503 (a dependency this route needs is unavailable — retryable, and nothing was written), 504 (the upstream request budget expired), 500 (unhandled). Switch on `code` where present, else `status`.

## Changes

- **2026-10-20** `e9e3e998e673`: 2 info
  - added the new optional `header` request parameter `X-RTA-Speech-Diagnostics`
  - added the optional property `data/items/speechDiagnostics` to the response with the `200` status

[Operation history](https://skmtc.dev/realtimeavatar/apis/realtime-avatar-api/changes/v1/usage/sessions/get.md)

---

[API](https://skmtc.dev/realtimeavatar/apis/realtime-avatar-api.md) · [All operations](https://skmtc.dev/realtimeavatar/apis/realtime-avatar-api/llms.txt) · [OpenAPI document](https://skmtc.dev/realtimeavatar/apis/realtime-avatar-api/revisions/e9e3e998e673?raw)