---
title: "Retrieve Speech-to-Video Session Usage"
method: GET
path: "/v1/usage/sessions"
tags: ["Usage"]
---

# Retrieve Speech-to-Video Session Usage

`GET /v1/usage/sessions`

## Request

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

Retrieve the usage of each speech-to-video session.

Lists the sessions created in the range, in UTC days, that have started
and ended.
The figures are seconds as your plan counts them, and cover every
workspace of your organization, so only an API key of the default
workspace can read them. Agent conversations and text-to-video are not
included.

The days are UTC calendar days, so they do not line up with your billing
period; Retrieve Usage gives the usage of your billing period. A range
spans at most 366 days and 10,000 sessions; split a busier range into
shorter ones.

## Query parameters

- `start` string, date, required: Earliest day a listed session was created, in UTC (YYYY-MM-DD).
- `end` string, date, required: Latest day a listed session was created, in UTC (YYYY-MM-DD).

## Response `200`

Successful Response

- SessionUsageResponse: Speech-to-video usage per session.
  - `data` SessionUsage[], required: Every ended session of the requested range, newest first.
    - `id` string, required: ID of the session.
    - `avatar_id` string, required: ID of the avatar of the session.
    - `started_at` string, required: Time the avatar started in the room in ISO 8601 format.
    - `ended_at` string, required: Time the session ended in ISO 8601 format.
    - `used_seconds` integer, required: Usage billed for the session: from the time the avatar started in the room until it last spoke.

## 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-28** `2d37d86bc5c1`: 1 breaking, 4 info
  - removed the required property `data/items/date` from the response with the `200` status
  - added the required property `data/items/avatar_id` to the response with the `200` status
  - added the required property `data/items/ended_at` to the response with the `200` status
  - added the required property `data/items/id` to the response with the `200` status
  - …1 more
- **2026-10-28** `264cb4adec1a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bey-dev/apis/beyond-presence-api/changes/v1/usage/sessions/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)