---
title: "Retrieve Usage"
method: GET
path: "/v1/usage"
tags: ["Usage"]
---

# Retrieve Usage

`GET /v1/usage`

## Request

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

Retrieve your organization's usage in the current billing period.

All 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. Usage can take a few minutes to appear.

## Response `200`

Successful Response

- UsageResponse: Usage of the current billing period.
  - `period_start` string, required: Start of the billing period in ISO 8601 format.
  - `period_end` string, required: End of the billing period in ISO 8601 format, exclusive.
  - `included_seconds` integer, required: Usage your plan includes in the billing period.
  - `used_seconds` integer, required: Usage billed in the billing period, including overage.
  - `remaining_seconds` integer, required: Usage your plan includes that is not used yet.
  - `overage_seconds` integer, required: Usage billed past what your plan includes. It only grows when usage-based billing is enabled.

## 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** `264cb4adec1a`: 1 info
  - endpoint added

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