---
title: "Retrieve a session"
method: GET
path: "/v1/avatar/sessions/{session_id}"
tags: ["Avatar Realtime"]
---

# Retrieve a session

`GET /v1/avatar/sessions/{session_id}`

## Request

- Base URL: `https://api.boson.ai`
- URL: `https://api.boson.ai/v1/avatar/sessions/{session_id}`
- Auth: HTTP bearer

Current state of a session. A session you did not create (with this API key) is reported as not found. Ended sessions stay retrievable until a few minutes after `expires_at`, then `404`.

## Path parameters

- `session_id` string, required

## Response `200`

The session object.

- AvatarSession: A realtime avatar session (the create / retrieve / release response).
  - `id` string: Session ID, e.g. `avrt_...`.
  - `object` 'avatar.realtime.session'
  - `status` 'active' | 'releasing' | 'terminated': `active`: the avatar is in the room. `releasing`: a release was requested and is not confirmed yet. `terminated`: the session has ended (released, expired, room emptied, or ended by Boson for another reason).
  - `model` string
  - `avatar_id` string
  - `avatar_identity` string: The LiveKit identity the avatar joined as (`transport.participant_identity`).
  - `created_at` string, date-time: When the avatar joined the room (ISO 8601, UTC).
  - `expires_at` string, date-time: Latest end time: the session ends at this time if it is still running (`created_at` + `max_duration_seconds`).
  - `ended_at` string, date-time, nullable: When the session ended; `null` while it is active.

## Other responses

- `401`: Missing or invalid API key.
- `404`: No session with that ID for this API key (`session_not_found`).
- `503`: Temporarily unavailable (`service_unavailable`, with `Retry-After`), or realtime avatar is not enabled on this server (`not_configured`).

## Changes

- **2026-11-03** `68bf7c248c4c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/boson/apis/boson-ai-api/changes/v1/avatar/sessions/:session_id/get.md)

---

[API](https://skmtc.dev/boson/apis/boson-ai-api.md) - [All operations](https://skmtc.dev/boson/apis/boson-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/boson/apis/boson-ai-api/revisions/68bf7c248c4c?raw)