---
title: "List session recordings"
method: GET
path: "/v1/recordings"
tags: ["Recordings"]
---

# List session recordings

`GET /v1/recordings`

## Request

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

List this workspace's private recordings, newest first. Metadata uses stable recording IDs and retainedUntil; download URLs are issued separately.

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

## Query parameters

- `sessionId` string
- `limit` integer
- `cursor` string

## Response `200`

Recordings

- ListRecordingsResponse
  - `data` union[], required
    - union
      - object
        - `sessionId` string, required
        - `recordingId` string, required
        - `mode` 'audio' | 'video' | 'audio_video', required
        - `createdAt` string, date-time, required
        - `retainedUntil` string, date-time, required
        - `participant` object
          - `participantIdentity` string, required
          - `role` 'user' | 'avatar', required
        - `mediaStartedAt` string, date-time
        - `mediaEndedAt` string, date-time
        - `mediaStartOffsetMs` integer: First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.
        - `mediaMutedIntervalsMs` object[]: Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.
          - `startMs` integer, required
          - `endMs` integer, required
        - `status` 'pending' | 'recording' | 'processing' | 'expired', required
      - object
        - `sessionId` string, required
        - `recordingId` string, required
        - `mode` 'audio' | 'video' | 'audio_video', required
        - `createdAt` string, date-time, required
        - `retainedUntil` string, date-time, required
        - `participant` object
          - `participantIdentity` string, required
          - `role` 'user' | 'avatar', required
        - `mediaStartedAt` string, date-time
        - `mediaEndedAt` string, date-time
        - `mediaStartOffsetMs` integer: First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.
        - `mediaMutedIntervalsMs` object[]: Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.
          - `startMs` integer, required
          - `endMs` integer, required
        - `status` 'ready', required
        - `mediaType` 'audio/mp4' | 'video/mp4' | 'audio/ogg' | 'video/webm', required
        - `sizeBytes` integer, required
        - `durationMs` integer, nullable, required
      - object
        - `sessionId` string, required
        - `recordingId` string, required
        - `mode` 'audio' | 'video' | 'audio_video', required
        - `createdAt` string, date-time, required
        - `retainedUntil` string, date-time, required
        - `participant` object
          - `participantIdentity` string, required
          - `role` 'user' | 'avatar', required
        - `mediaStartedAt` string, date-time
        - `mediaEndedAt` string, date-time
        - `mediaStartOffsetMs` integer: First playable native media timestamp relative to mediaStartedAt. Playback retains this offset; it does not reset the file clock to zero.
        - `mediaMutedIntervalsMs` object[]: Intervals of hidden camera video relative to mediaStartedAt, using native media timestamps. Audio playback continues through these intervals.
          - `startMs` integer, required
          - `endMs` integer, required
        - `status` 'failed', required
        - `errorCode` 'recording_failed' | 'recording_unavailable', required
  - `nextCursor` string, nullable, required

## Other responses

- `400`: Invalid query
- `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`.

---

[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)