> ## Documentation Index
> Fetch the complete documentation index at: https://usenaive.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Spend

> GET /v1/spend — company spend by tenant, with each tenant's cap and whether that cap is actually enforced.

```
GET /v1/spend?period=day|week|month|year
```

Real rows from the tenant spend ledger, grouped by tenant, with each tenant's
declared cap beside its spend.

`period` defaults to `month`. Anything outside the four values is
`400 invalid_input`.

<ResponseExample>
  ```json 200 theme={"theme":"css-variables"}
  {
    "period": { "name": "month", "start": "2026-07-01T00:00:00.000Z" },
    "environment_scoped": false,
    "environment_scoped_note": "this sum spans sandbox and production; the closed reserve path scopes to one environment, so this number can exceed what any single cap counted",
    "buckets": [
      {
        "key": "8f1c…",
        "label": "acme-support",
        "cents": 1840,
        "cap_cents": 5000,
        "class": "reserve",
        "enforced": true,
        "cap_period": "month"
      },
      {
        "key": "b207…",
        "label": "pilot-2",
        "cents": 920,
        "cap_cents": 2000,
        "class": "meter",
        "enforced": false,
        "cap_period": "month"
      }
    ]
  }
  ```
</ResponseExample>

## `class` and `enforced`

| `class`   | `enforced` | Behaviour at the cap                                                                                                     |
| --------- | ---------- | ------------------------------------------------------------------------------------------------------------------------ |
| `reserve` | `true`     | The amount is reserved atomically, under an advisory lock, **before** the action executes. Over-cap actions are refused. |
| `meter`   | `false`    | Spend is recorded. A soft cap escalates to approval; no cap meters only. Nothing is refused on the basis of this number. |

`class` is `reserve` only when the tenant's budget declares `hard: true`.

## `environment_scoped: false`

<Warning>
  This sum spans sandbox and production; the cap it is compared against scopes to one
  environment. `cents` can therefore exceed `cap_cents` while nothing was ever refused. If
  you alert on "spend approaching cap", restrict tenants to one environment or expect false
  positives from sandbox traffic.
</Warning>

## This sum is attribution, not the ledger

A row appears here only when the spend was attributed to a profile; usage charged outside
a resolved subject (e.g. the legacy orchestration container) lands in the company credit
ledger with no row here. For a total that does not depend on attribution, read
`GET /v1/billing/transactions` and treat this endpoint as the per-tenant governance view.

## Buckets are tenants, not actions

One row per tenant. `key` is the `tenant_user_id`; `label` is the tenant's label,
falling back to its external id, falling back to `null`.

For a per-action breakdown of one tenant, use
[`GET /v1/teams/{team}/tenants/{tenantUserId}/cost`](/docs/api-reference/runtime/cost)
— and note that `enforced` on that endpoint answers a different question and is
always `false`.

## Windows

`period.start` is computed from the requested period, not from any tenant's own
budget window. `cap_period` on each bucket is that tenant's actual cap window. If
they differ, the spend figure and the cap are measured over different spans —
compare `cap_period` to `period.name` before dividing one by the other.