---
title: "Retrieve Speech-to-Video Session"
method: GET
path: "/v1/sessions/{id}"
tags: ["Speech-to-Video Sessions"]
---

# Retrieve Speech-to-Video Session

`GET /v1/sessions/{id}`

## Request

- Base URL: `https://api.bey.dev`
- URL: `https://api.bey.dev/v1/sessions/{id}`
- Auth: API key in header `x-api-key`

Retrieve a single speech-to-video session by ID.

## Path parameters

- `id` string, required: Speech-to-video session ID.

## Response `200`

Successful Response

- union
  - LivekitSessionResponse: Response body for a LiveKit speech-to-video session.
    - `id` string, required: Unique identifier of the object in the database.
    - `transport` 'livekit'
    - `avatar_id` string, required: ID of avatar to use.
    - `status` union, required
      - SessionStatusToStart: Session that has not yet started.
        - `type` 'to_start'
      - SessionStatusOngoing: Session that is currently ongoing.
        - `type` 'ongoing'
        - `started_at` string, required: Start time in ISO 8601 format.
      - SessionStatusCompleted: Session that has completed.
        - `type` 'completed'
        - `started_at` string, required: Start time in ISO 8601 format.
        - `ended_at` string, required: End time in ISO 8601 format.
    - `url` string, required: URL of LiveKit server the avatar worker should connect to.
  - PipecatSessionResponse: Response body for a Pipecat speech-to-video session.
    - `id` string, required: Unique identifier of the object in the database.
    - `transport` 'pipecat'
    - `avatar_id` string, required: ID of avatar to use.
    - `status` union, required
      - SessionStatusToStart: Session that has not yet started.
        - `type` 'to_start'
      - SessionStatusOngoing: Session that is currently ongoing.
        - `type` 'ongoing'
        - `started_at` string, required: Start time in ISO 8601 format.
      - SessionStatusCompleted: Session that has completed.
        - `type` 'completed'
        - `started_at` string, required: Start time in ISO 8601 format.
        - `ended_at` string, required: End time in ISO 8601 format.
    - `url` string, required: URL of Daily room the video bot should connect to.

## Other responses

- `401`: Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.
- `402`: The plan's usage limit has been reached, or the requested feature requires a plan upgrade.
- `403`: The API key is valid but not permitted to perform this action, because the resource belongs to someone else.
- `404`: The requested resource does not exist or is not accessible with this API key.
- `422`: The request is malformed. `detail` lists each field that failed validation, where it was located, and why.
- `429`: The plan's limit on the number of concurrent sessions has been reached.

## Changes

- **2026-10-20** `0469e200c235`: 1 info
  - added the non-success response with the status `402`
- **2026-10-16** `c8f80740b51c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bey-dev/apis/beyond-presence-api/changes/v1/sessions/:id/get.md)

---

[API](https://skmtc.dev/bey-dev/apis/beyond-presence-api.md) - [All operations](https://skmtc.dev/bey-dev/apis/beyond-presence-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bey-dev/apis/beyond-presence-api/revisions/2d37d86bc5c1?raw)