---
title: "Budget status"
method: GET
path: "/client/budget"
tags: ["Usage"]
---

# Budget status

`GET /client/budget`

## Request

- Base URL: `https://api.roar-ai.com`
- URL: `https://api.roar-ai.com/client/budget`
- Auth: HTTP bearer

Real-time spend vs. cap per budgeted scope, and the company credit balance (`balanceUsd`). Requires `usage:read`.

## Response `200`

Budget report

- BudgetReport
  - `balanceUsd` number, required: The company's prepaid credit balance in USD — the number on Billing. Readable by any key with `usage:read`, so an app can warn before it runs out. The statement and top-ups are not available to keys.
  - `data` BudgetStatus[], required
    - `scope` 'client' | 'project' | 'key', required
    - `id` string, uuid, required
    - `name` string: Absent for an unnamed key
    - `spendLimitUsd` number, required
    - `budgetPeriod` 'day' | 'week' | 'month' | 'total', required
    - `hardCap` boolean, required
    - `alertAtPct` integer, required
    - `periodStart` string, date-time, required
    - `spendUsd` number, required
    - `pctUsed` number, nullable, required
    - `state` 'ok' | 'alerting' | 'exceeded', required
  - `summary` object, required
    - `tracked` integer, required
    - `alerting` integer, required
    - `exceeded` integer, required

## Other responses

- `403`: Key lacks usage:read

---

[API](https://skmtc.dev/roar-ai/apis/roar-ai-api.md) · [All operations](https://skmtc.dev/roar-ai/apis/roar-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roar-ai/apis/roar-ai-api/revisions/37e4d0d5a7fe?raw)