Budgets, spend and usage#

A budget is a spending limit for an agent, a namespace, a user or a tenant, over a session, a day or a month. Spend is the metered cost so far in a budget window; cost is the metered price of one call or session; usage is the metered units for billing (sandbox seconds, governed calls, model tokens, approvals). The gateway meters every governed call, and checks every applicable budget before it forwards the next tool or model call.

Where budgets come from#

The operator merges all of them into one document, budgets.json in the ConfigMap maqpna-budgets. When two sources set the same limit, the smallest limit and the strictest onExceed win. Amounts are never converted between currencies: a document mixing currencies is rejected and the gateway keeps the previous budgets.

What is counted#

The gateway prices each call with the pricing table (pricingFile):

• tool calls: defaultToolCallUSD, or a toolCalls entry matching server/tool (most specific glob wins);
• model calls: prompt and completion tokens from the upstream's usage, times models.<name>.inputPer1kUSD / outputPer1kUSD;
• sandbox time: seconds from the operator's usage report, times sandboxPerSecondUSD.<tier>.

Spend is kept per session, per agent, per namespace, per user and in total, with day and month windows in budgetTimezone (default UTC). A new day or month starts from zero; there is no reset job. A forked session's spend also counts against its lineage root's per-session budget, so N forks share one budget.

What happens when a budget is reached#

Spend equal to or above a limit counts as exhausted, so a call that would start beyond the budget is refused.

alertAtPercent (for example [80, 100]) sends a budget.threshold notification once per limit, period and level. Token-rate limits are separate from money: tokensPerMinute reserves an estimate (body bytes ÷ 4) before a model call and settles it with the reported usage; when the window is exhausted the call gets HTTP 429 with Retry-After. maxTokensPerRequest clamps max_tokens.

flowchart LR
    C["Next tool or model call<br/>for session S of agent A,<br/>namespace N, user U"] --> L{"For each limit:<br/>agent, namespace, user<br/>× session, day, month"}
    L -- "spend below every limit" --> F["Forward"]
    L -- "a limit reached" --> O{"onExceed"}
    O -- deny --> D["Denied<br/>budget_exceeded:scope/window"]
    O -- require_approval --> H["Held for approval<br/>(tool calls only)"]
    O -- alert --> N["Allowed + budget.exceeded<br/>notification"]
    F --> M["Meter the cost<br/>(after the call)"]

What you see#

maqpna budgets list shows every limit and the spend against it (columns from cmd/maqpna/admin_finops.go; values illustrative):

SCOPE      KEY           WINDOW  PERIOD      SPENT USD  LIMIT USD  EXCEEDED
agent      team-a/coder  day     2026-10-02  4.21       10         false
namespace  team-a        month   2026-10     187.5      200        false

maqpna costs summary --session S prints one line per session, for example session fix-4821: $0.42 (tools 0.02, models 0.4, sandbox 0); 12 tool calls, 3 model calls, 5120/860 tokens in/out. maqpna costs focus exports FOCUS, the FinOps cost-export format. See maqpna budgets list, maqpna costs summary and maqpna costs focus.

Related#

• Budget enforcement
• Usage metering and node counting
• Model call governance