# Credits and usage

> How credit works, how to read your balance and usage from the API, what a 402 means, and which plan limits you can run into.

Everything that spends is priced in **credits**, debited from your organisation's balance. Your plan grants an allowance of credits each cycle. Two endpoints tell you where you stand:

```bash title="curl"
curl https://api.lumavox.ai/v1/plan -H "Authorization: Bearer $API_KEY"
```

```json title="Response"
{
  "plan_slug": "pro",
  "plan_name": "Pro",
  "monthly_credits_micros": 100000000000,
  "credit_balance_micros": 73412500000,
  "period_end": "2026-11-01T00:00:00.000Z"
}
```

Both need a key with the **`usage:read`** scope (or the master key). It is a scope of its own so that a key handed out for one capability cannot see what the whole organisation spends.

Credit amounts are **integers of micro-credits**: `1000000` is one credit, so `73412500000` above is 73,412.5 credits. Integers add and compare exactly — divide by a million only to show a person. See [Conventions](https://docs.lumavox.ai/conventions.md#credits).

## Your balance: `GET /v1/plan`

| Field | What it is |
|---|---|
| `plan_slug`, `plan_name` | the plan your organisation is on |
| `monthly_credits_micros` | what the plan grants each cycle |
| `credit_balance_micros` | what is left now |
| `period_end` | when the current cycle ends |

The answer is `null` when your organisation has no subscription.

`credit_balance_micros` can be above `monthly_credits_micros` after a manual adjustment, and slightly below zero inside the plan's grace buffer.

`GET /v1/plan` is cheap: poll it freely. Check it before queueing a batch, rather than finding out from a `402` halfway through.

## Your usage: `GET /v1/usage`

A report over whole UTC days up to now — totals, a breakdown by capability, a daily series and a split by key, plus the same plan and balance as `GET /v1/plan`.

```bash title="curl"
curl "https://api.lumavox.ai/v1/usage?days=7" -H "Authorization: Bearer $API_KEY"
```

| Query | What it does |
|---|---|
| `days` | the window: from midnight UTC `days` days ago until now, so its first day counts whole; 1 to 365, 30 by default |

| Field | What it is |
|---|---|
| `since`, `until` | the window: `since` is midnight UTC of its first day, `until` is now |
| `plan` | your plan and balance, or `null` with no subscription |
| `total_requests`, `total_seconds` | totals over the window |
| `by_capability` | one entry per capability, model and event type: `requests`, `units_seconds`, `credits_micros` |
| `daily` | one entry per UTC day across the whole window — days with no traffic included — with `requests` and `units_seconds` |
| `by_key` | which key spent what, busiest first; a deleted key shows as `Deleted key` with a null `api_key_id` |

`units_seconds` is seconds of audio generated. `credits_micros` is what was charged, and is `null` for a group nothing has priced. A non-zero `unpriced_requests` means that group's `credits_micros` leaves some requests out, so treat it as a floor.

The report is read from daily totals, a few rows a day; only `by_key` counts the window's requests one by one. For the balance alone, call `GET /v1/plan`.

## When you are charged

- **Speech and transcription in the response** are charged for the request itself: `POST /v1/tts` per thousand characters of text, `POST /v1/stt` per minute of audio.
- **Queued jobs** are charged when they are accepted and refunded in full if they fail. See [queued jobs](https://docs.lumavox.ai/jobs.md).
- **Agents' conversations** are paid from the ephemeral key the end user holds. A key's `credit_limit_micros` is **set aside from your balance when it is minted**, and what it does not spend comes back when it expires, runs out or is revoked. See [end users and their keys](https://docs.lumavox.ai/agents/end-users.md).

Each endpoint's reference says what its price depends on.

## Out of credit: 402

When a charge takes your balance to the plan's grace buffer or below, your organisation is **suspended**:

- every request made with your organisation's API keys answers **402** `insufficient_credits`;
- every live ephemeral key is revoked, and what it had not spent comes back to the balance.

```json title="Response — 402"
{
  "error": {
    "code": "insufficient_credits",
    "message": "This organisation has run out of credits. Usage resumes when the next monthly allowance is granted, or immediately if an administrator adds credits.",
    "request_id": "8f3c2a1b9d4e5f60",
    "issues": []
  }
}
```

It lifts by itself when credit arrives — the next cycle's allowance, or credit an administrator adds — and nothing has to be re-enabled.

Minting an ephemeral key also answers **402** when the balance cannot cover the `credit_limit_micros` you asked to set aside, and so does a queued job whose estimate would take the balance past the grace buffer — refused before anything is charged. The buffer absorbs what was already running when credit ran out, never a job that would overdraw it on its own.

Your organisation's members are emailed when the balance falls to a fifth of the monthly allowance, and again when it runs out.

## Plan limits

Besides credit, your plan sets limits you can run into:

| Limit | When you hit it |
|---|---|
| requests a minute, requests an hour, requests at the same time — for the organisation, and per capability | **429** with `Retry-After`; see [rate limits](https://docs.lumavox.ai/errors.md#rate-limits) |
| unfinished videos at once | **429** from `POST /v1/videos`, nothing charged |
| how many agents, voices and end users you hold | **409** when you create one more |
| ephemeral keys: a key's credit limit and lifetime, how many each end user may hold, how many you mint a minute, how much credit live keys may hold at once | **422**, **429** or **402** from `POST /v1/ephemeral-keys`; `GET /v1/ephemeral-keys/limits` lists them |

The platform sets limits of its own besides your plan's — the size of an upload, the tools on an agent, the unfinished generations at once, the ceilings on an ephemeral key: see [Limits](https://docs.lumavox.ai/limits.md).

## Related

- [Limits](https://docs.lumavox.ai/limits.md)
- [Errors and limits](https://docs.lumavox.ai/errors.md)
- [Queued jobs](https://docs.lumavox.ai/jobs.md)
- [API reference: usage](https://docs.lumavox.ai/reference/usage.md)