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

# Monthly usage

> How much of the upstream USD budget the user has burned this month.

<ResponseExample>
  ```json 200 theme={null}
  {
    "upstream_usd_used":   12.34,
    "upstream_usd_budget": 50.00,
    "fraction_used":       0.2468,
    "over_cap":            false,
    "month":               "2026-05"
  }
  ```
</ResponseExample>

When `over_cap` becomes true, every paid endpoint returns
`402 monthly_cost_cap` until the next month rolls over. This protects
Lavendly's margin from a single user driving an unbounded loss.

<Note>
  Cost is recorded from the underlying generation provider's billing
  data, actual dollars, not an estimate. See
  `/v1/usage/top?limit=20` for the per-user spend leaderboard
  (admin-only).
</Note>