Usage Costs and Budgets

Your organization owns each upstream provider account. The provider bills your organization directly.

Verdictan does not buy provider capacity for you. Verdictan does not receive or settle a provider invoice.

Verdictan gives cost estimates, budget controls, and spend logs on top of your own provider contract.

Which record is authoritative

Record	Owner	Status
Provider invoice and provider console usage	Your provider account	Authoritative for money
Verdictan price estimate	Verdictan ai_model_pricing data	Estimate for planning and control
Verdictan spend log	Verdictan control plane	Estimate for attribution and analysis

Use the provider invoice for accounting. Use Verdictan values for engineering attribution, budget control, and trend analysis.

A Verdictan amount can be different from the provider amount. Provider discounts, committed-use contracts, taxes, and rounding are not in the estimate.

Which surface to use

Question	Best surface
What is causing cost, tokens, or request volume at this time?	Usage
Which cost-governance threshold or declared hard limit is configured?	Budgets
Which provider or model is close to a configured headroom limit?	verdictan spend provider-budget
Which API token or scope budget is close to exhaustion?	API Tokens or verdictan spend budget
What did the provider actually bill?	Your provider invoice

Usage: cost analysis

Use Usage to answer these questions:

• Which provider, model, team, user, or agent is causing cost?
• Did cost increase after a rollout?
• Which slice must you export for a finance or engineering review?

Usage is the cost analysis surface. Teams use it to examine requests, tokens, estimated costs, and attribution quality during a selected period.

Cost amounts on Usage come from token counts and configured pricing metadata. They are estimates. They are not customer invoices.

Example cost explorer with synthetic usage data.

Organization storage

Open Organization to examine retained storage at this time. The storage section shows the customer quota, the History and event burst, and the compliance evidence reserve.

The default customer quota is 10 MiB. History sessions and ordinary events can use a different 1 MiB burst. Verdictan can remove the oldest eligible sessions and events when these records use the burst. It does not automatically remove configurations, agents, exports, or other organization resources.

New storage growth stops when the applicable limit is full. Operations that reduce storage remain available when the customer storage pool is full. A 507 Insufficient Storage response identifies a request that cannot add more retained data.

Data that you mark for deletion continues to use storage until Verdictan deletes the data. Preserved and immutable data continues to use storage while its protection is active.

How Verdictan calculates an estimate

1. The gateway estimates the token count before dispatch.
2. Verdictan reads the unit prices from a pricing snapshot.
3. Verdictan calculates an estimated cost for the authorization decision.
4. After the response, Verdictan records the actual token counts.
5. Verdictan writes a spend log row with the calculated cost.

Each pricing snapshot has an identifier. Use the identifier when you must explain a historical estimate.

If a model has no pricing metadata, Verdictan cannot calculate a cost estimate. A budget limit that must have an estimate does not apply to that model.

Budget controls are different systems

The word budget is on more than one surface. These surfaces store different records.

Control	Configure or examine it in	Active request-path boundary
Cost governance budget	Console Usage → Budgets	Stores cost-governance thresholds, alert settings, and declared hard-limit state. Verify the applicable deployment path before you identify it as a gateway block.
Scope spend budget	verdictan spend budget or /v1/budgets	Tracks organization, team, user, or key spend. A standalone gateway with an event sink can use remaining headroom. A connected gateway does not load these scope records for routing.
Provider budget	verdictan spend provider-budget	Participates in provider-headroom limits for configured gateway traffic. A target must also have pricing metadata for estimated-cost steering.
Governed API-token budget	API Tokens or verdictan token ... --max-budget	The API examines depletion for requests that use that token.

Do not use a value in one budget view as proof about a different request path.

Budgets: thresholds and declared limits

Use Budgets to do these tasks:

• Set or review budget amounts.
• Review declared hard-limit and alert-threshold state.
• Scope a budget to the organization, a team, a user, or an agent where supported.

Budgets are the cost-governance workflow. Use them when the question is about configured thresholds and state.

The budget amounts and scopes in this image are synthetic.

A Verdictan budget limits traffic that goes through Verdictan. It does not limit spend at the provider. Set a provider-side limit in the provider console when you must have a hard money limit.

Spend logs

Verdictan writes one spend log row for each completed authorization. Each row records the provider, model, token counts, estimated cost, and attribution.

Spend logs use byok as the credential origin for new rows. Historical rows from the retired platform-managed access mode keep their original label.

Export a spend log slice when finance or engineering must reconcile Verdictan attribution with the provider invoice.

How teams usually divide ownership

• Engineering uses Usage, request IDs, and verdictan events or GET /v1/events. Set since to correlate cost changes with rollout changes. Capture-enabled History adds session context only when the configured mode and platform retention policy make it available.
• Operations uses Budgets and provider-budget settings to monitor configured limits and upstream provider headroom.
• Finance uses the provider invoice as the authoritative record. Finance uses exported Verdictan usage slices for attribution.

When cost controls change traffic

If a request cannot continue and the error shows a spend or budget issue:

1. Preserve the response code, error code, request ID, token ID, provider, and model.
2. Examine the active control for that path. The control can be a token, budget, provider headroom limit, or authorization policy.
3. Use Budgets for cost-governance context.
4. Send the request again only after you understand the owning control and its approved change.

Next steps

• verdictan spend
• Providers and BYOK Routing
• Config-First Workflow
• verdictan events