Skip to main content
GET
/
v1
/
usage
/
monthly
Monthly usage
curl --request GET \
  --url https://api.example.com/v1/usage/monthly
{
  "upstream_usd_used":   12.34,
  "upstream_usd_budget": 50.00,
  "fraction_used":       0.2468,
  "over_cap":            false,
  "month":               "2026-05"
}

{
  "upstream_usd_used":   12.34,
  "upstream_usd_budget": 50.00,
  "fraction_used":       0.2468,
  "over_cap":            false,
  "month":               "2026-05"
}
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.
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).