AI Budget

The per-user AI credit budget endpoint. Tenant-wide usage reporting (summaries, monthly trends, top consumers) lives in the Usage & Credits section.

Moved endpoints

The old GET /api/ai-usage and GET /api/ai-overview admin endpoints have been removed. Tenant-wide consumption is now served by GET /api/usage, GET /api/usage/monthly, and GET /api/usage/top-consumers.

GET /api/ai-budget

Get the authenticated user's AI credit budget status — their effective usage profile, month-to-date consumption against any per-actor cap, and the tenant credit pool.

Authentication: Required (AI access)

Pre-blocks: ai.verify

Response:

{
  "configured": true,
  "byok": false,
  "slushActive": false,
  "profile": {
    "name": "Standard",
    "slug": "standard",
    "creditCapPerMonth": 5000,
    "allowedModelTiers": ["everyday", "advanced"],
    "features": []
  },
  "monthly": {
    "creditsUsed": 1234.5,
    "creditCap": 5000,
    "percentUsed": 24.7,
    "resetsAt": "2026-06-01T00:00:00Z",
    "isUnlimited": false
  },
  "pool": {
    "included": 50000,
    "used": 12340,
    "remaining": 37660,
    "overageRate": 1.0
  }
}

Fields:

Field	Type	Description
`configured`	boolean	Whether AI is configured — `true` once the entitlement cache holds a valid License Manager JWT. Clients use this to block sends and show an upgrade CTA instead of hitting a `402`.
`byok`	boolean	Whether the tenant uses its own provider keys. When `true`, AI calls do not draw from the credit pool.
`slushActive`	boolean	`true` when the paid pool is empty and consumption is drawing on the internal safety buffer.
`profile`	object \| null	The user's effective usage profile (`null` if none applies).
`monthly.creditsUsed`	number	Credits consumed by this user month-to-date.
`monthly.creditCap`	integer \| null	The profile's monthly cap (`null` = unlimited, `0` = hard stop).
`monthly.percentUsed`	number	Percent of the monthly cap consumed.
`monthly.resetsAt`	date	When the monthly cap resets (start of next month).
`monthly.isUnlimited`	boolean	`true` when configured with no monthly cap.
`pool`	object	The tenant credit pool (`included`, `used`, `remaining`, `overageRate`).

Credit metering

AI requests are metered in credits derived from model token usage and the License Manager rate card. Enforcement happens before each request — see the enforcement flow. A request that would exceed a cap, budget, or the pool returns 402 Payment Required with a machine-readable code.

GET /api/ai-budget​

GET /api/ai-budget