# Usage

> What your organisation has spent, and what it has left.

What your organisation has spent, and what it has left.

When and why to call these: the [usage guide](https://docs.lumavox.ai/usage.md).

## Usage for your organisation

`GET /v1/usage`

Totals, a per-capability breakdown, a daily series and a per-key split over a window ending now, plus your plan and balance. `units_seconds` is seconds of audio generated; `credits_micros` is what was charged, and is null for a group nothing has priced yet.

A report — four aggregates over the window. Poll `GET /v1/plan` for the balance alone.

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

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `days` | integer |  | Window ending now 1–365. Default `30`. |

**Responses**

| Status | Description |
|---|---|
| `200` | `application/json` — The report |
| `400` | The request could not be read: malformed JSON |
| `401` | Missing or invalid credentials |
| `403` | The key is valid but its scopes do not cover this capability — a key limited to `tts` gets this from `/v1/images` rather than a 401 |
| `422` | The request failed validation |
| `429` | Rate limit exceeded |

**`200` response body**

| Field | Type | Description |
|---|---|---|
| `org_id` | string |  |
| `since` | string (date-time) |  |
| `until` | string (date-time) |  |
| `plan` | OrgPlan or null | The organisation's subscription and remaining credits, or null if it is not on a plan. |
| `plan.plan_slug` | string |  |
| `plan.plan_name` | string |  |
| `plan.monthly_credits_micros` | integer | What the plan grants each cycle. |
| `plan.credit_balance_micros` | integer | What is left: may exceed the grant after a manual adjustment, and be slightly negative inside the grace buffer. |
| `plan.period_end` | string (date-time) |  |
| `total_requests` | integer |  |
| `total_seconds` | number |  |
| `by_capability` | array of UsageSummary |  |
| `by_capability[].capability` | string |  |
| `by_capability[].model` | string or null |  |
| `by_capability[].event_type` | string or null |  |
| `by_capability[].requests` | integer |  |
| `by_capability[].units_seconds` | number |  |
| `by_capability[].credits_micros` | integer or null | What was charged; null when nothing in the group was priced. |
| `by_capability[].unpriced_requests` | integer | Requests in this group with no price recorded. Their credits are not in the sum, so a non-zero value here means the total is a floor. |
| `daily` | array of UsageDay | One entry per UTC day across the whole window, **including days with no traffic**. Gap-filled server-side so a chart can plot it directly rather than every client reinventing the same fill. |
| `daily[].date` | string (date) |  |
| `daily[].requests` | integer |  |
| `daily[].units_seconds` | number |  |
| `by_key` | array of UsageByKey | Which credential spent the quota, busiest first. |
| `by_key[].api_key_id` | string or null | Null once the key has been deleted |
| `by_key[].name` | string | Key label, or 'Deleted key' if it is gone |
| `by_key[].requests` | integer |  |
| `by_key[].units_seconds` | number |  |
| `by_key[].credits_micros` | integer or null | What was charged; null when nothing in the group was priced. |
| `by_key[].unpriced_requests` | integer | Requests in this group with no price recorded. Their credits are not in the sum, so a non-zero value here means the total is a floor. |

## Your plan and credit balance

`GET /v1/plan`

What plan your organisation is on, what it grants each cycle, what is left, and when the cycle ends. Two indexed lookups, so poll it freely — this is what to check before queueing a batch rather than learning from a 402.

`credit_balance_micros` may exceed `monthly_credits_micros` after a manual adjustment, and may be slightly negative inside the grace buffer. Null when the organisation has no subscription.

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

**Responses**

| Status | Description |
|---|---|
| `200` | `application/json` — The plan and balance, or null with no subscription |
| `401` | Missing or invalid credentials |
| `403` | The key is valid but its scopes do not cover this capability — a key limited to `tts` gets this from `/v1/images` rather than a 401 |
| `422` | The request failed validation |
| `429` | Rate limit exceeded |