Skip to main content

Pre-flight AI Budget Check

GET 
/api/v1/stats/ai/budget

Pre-flight budget check called by the Chat Proxy before every chat request. Returns the credit pool balance and effective credit sub-limits across daily, weekly, and monthly periods. The credits.allowed flag is the single go/no-go signal.

The backend derives usergroup_id from the authenticated user's JWT. No query parameters are needed.

Enablement requires both the AI_ASSISTANT addon to be added+enabled on the user account and ai_settings.enabled = true for the group.

Credit Budget Resolution​

Each period's limit is the effective limit — the lower of the group-level limit (ai_settings) and the per-user limit (ai_user_budget). The used and remaining values reflect the requesting user's own consumption, not group-wide totals.

  • limit: 0 means no sub-limit for that period (pool balance is the only constraint).
  • remaining: null means no cap is enforced for that period.
  • credits.allowed is false when the feature is disabled, the credit pool balance is zero, or any effective sub-limit is exhausted.

Proxy Decision Logic​

if !response.enabled:
    → reject with SSE error "ai_disabled"
if !response.credits.allowed:
    → reject with SSE error "credits_exhausted"
else:
    → proceed with Anthropic call

Fail-Open Policy​

If this endpoint returns 500+, the proxy allows the chat request (fail-open to avoid blocking users due to backend issues).

Responses​

Budget status for the account