> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Budgets & FinOps

> Per-agent USD budgets with warn/block enforcement, and per-call cost attribution by user, team, model, and agent — priced from a versioned pricebook that never records $0 silently.

# 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**:

| Action  | Behavior at the cap                                                                   |
| ------- | ------------------------------------------------------------------------------------- |
| `warn`  | Allow the call, set the `X-Knox-AI-Budget-Warning` response header, record a warning. |
| `block` | Reject calls once the cap is reached (`HTTP 402`-style budget block).                 |

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>`.

```bash theme={"dark"}
# CSV of last-30-day spend by team
curl "https://api.knoxcall.com/v1/ai-gateway/usage/export?group_by=team&period=30d&format=csv" \
  -H "Authorization: Bearer tk_live_..."

# JSON grouped by a cost-center tag
curl "https://api.knoxcall.com/v1/ai-gateway/usage/export?group_by=tag:cost_center&period=90d" \
  -H "Authorization: Bearer tk_live_..."
```

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](/ai-gateway/pii-redaction))
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](/ai-gateway/observability) for your own dashboards.