Skip to main content

​
Budgets & FinOps

Every call through the gateway is priced and attributed, and agents can carry budgets that warn or hard-block before overspend.

​
Pricing

Cost is computed from a versioned pricebook shipped with KnoxCall (packs/ai-gateway-pricebook/), covering current Anthropic, OpenAI, and Gemini models with dated price rows. Two guarantees matter:
  • Never silently $0. If a model isn’t in the pricebook, the call is recorded with cost_source = 'unpriced' and surfaced through an unpriced_request_count — never booked as free. Provider inference falls back across providers rather than dropping to zero.
  • No remote config fetch. The pricebook is local — there is no run-time call to a third-party price feed. A weekly in-process check flags any observed-but-unpriced models via an alertable ai_gateway.unpriced_model audit event, so you update the manifest deliberately.
Each usage row records cost_source (pricebook / unpriced / cache_hit).

​
Budgets

Attach a budget to an agent with a daily and/or monthly USD cap and an overage action: The current utilization is returned on every call as X-Knox-AI-Budget-Pct. Budgets are stored in a cross-worker store (Redis when enabled) so the cap holds across all workers, not per-process.

​
Attribution

Every call is attributed so you can build showback/chargeback:
  • User — pass X-KC-User (a SCIM user id) on the request.
  • Team — resolved from the attribution directory.
  • Model and agent — recorded automatically.
The Usage tab on the gateway detail page reads the raw usage ledger (which carries the team attribution and cost_source that the daily rollup drops) and surfaces unpriced requests so a pricing gap is visible rather than hidden.

​
Showback / chargeback exports

Export aggregated spend for any period, grouped by the dimension your finance team bills on — user, team, agent, model, provider, or a custom tag (cost_center / project / …). Tag agents via their tags field, then group by tag:<key>.
Each row carries requests, input_tokens, output_tokens, cost_usd, and unpriced_requests (so a pricing gap is visible, never hidden). group_by is a strict whitelist and a tag key is bound as a parameter — no injection surface.

​
Provable budget enforcement

“Budgets” that only warn are theatre. KnoxCall’s enforcement is covered by a test suite that exercises each overage action against the budget store:
  • block — once the daily/monthly cap is reached, further calls are rejected before reaching the upstream (no spend past the cap).
  • warn — the call proceeds with X-Knox-AI-Budget-Warning; nothing is silently dropped.
  • per-call token ceiling — a request asking for more output than the agent’s budget_per_call_max_tokens is rejected up front, so one call can’t blow the budget in a single shot.
Enforcement reads a cross-worker store (Redis when enabled) so the cap holds across every worker, not per-process. Cache hits (exact caching) cost 0 and never charge the budget.

​
Where to look

  • Usage tab — spend and request counts by period, with attribution + export.
  • Models tab — the effective pricebook and each model’s allowlist status.
  • OpenTelemetry — knoxcall.ai_gateway.cost_usd on every span for your own dashboards.