Cost & Caps

Partial feature. Cost event recording and the cap policy matrix are fully wired. Hard enforcement of spend limits requires model-catalog pricing rows to be populated for your active providers - raw_cost_usd stays null until those rows exist, which means cap limits can be recorded but not meaningfully enforced yet. Operators should treat current cost totals as estimates pending pricing data.

Rensei tracks spend per agent session through the cost_events table and enforces configurable budget caps through the organizations.cap_policy JSONB column. This page covers how cost events are recorded, how the cap matrix is structured, and how to configure limits.

Cost events

Every completed dispatch session writes one row to cost_events. The key fields are:

Prop

Type

Cost events are written by the validateBudgetCap path in the worker dispatch chain (src/lib/worker-fleet/dispatch.ts). The event is appended after the session reaches a terminal state.

`billingClass` derivation

billingClass is a composite string combining authMode and providerId, normalised to lowercase with a dot separator:

byok.anthropic
metered.anthropic
metered.openai
host-session.anthropic

This value is what the Stripe billing pipeline uses for line-item labelling and what the admin spend dashboard groups by.

The cap policy matrix

Budget caps live in organizations.cap_policy, a JSONB column with one entry per (authMode, providerId) cell:

{
  "cells": [
    {
      "authMode": "metered",
      "providerId": "anthropic",
      "dailyCapUsd": 50.00,
      "monthlyCapUsd": 1000.00,
      "perSessionCapUsd": 5.00
    },
    {
      "authMode": "byok",
      "providerId": "openai",
      "dailyCapUsd": null,
      "monthlyCapUsd": 500.00,
      "perSessionCapUsd": null
    }
  ]
}

A null value on any cap means that cap axis is not enforced. An absent cell means the auth-mode/provider combination has no cap.

Cap enforcement

validateBudgetCap runs before dispatch. It:

Looks up the (authMode, providerId) cell for the session.
Aggregates cost_events over the relevant window (day or month) for the org.
If the running total plus the estimated session cost would exceed the cap, the dispatch is rejected with a BudgetCapExceeded error before the session starts.

Cap enforcement depends on raw_cost_usd being non-null. With null costs, only perSessionCapUsd = 0 (which blocks all sessions for that cell) is reliably enforceable. Fill out model-catalog pricing rows to enable real-time cap checks.

Admin spend dashboard

Navigate to Admin → Billing → Spend to view:

Running daily and monthly totals by billingClass
Per-org and per-project breakdowns
A time-series chart of spend per provider
Session-level drill-down (click any row)

The dashboard aggregates from cost_events in real time.

Configuring caps

Navigate to Admin → Billing → Cap Policy.
Select the org you want to configure.
Add or edit cells in the (authMode × provider) matrix.
Save. Caps take effect on the next dispatch attempt.

PATCH /api/admin/billing/cap-policy/<orgId>
Content-Type: application/json
Authorization: Bearer rsk_live_...

{
  "cells": [
    {
      "authMode": "metered",
      "providerId": "anthropic",
      "dailyCapUsd": 50.00,
      "monthlyCapUsd": 1000.00,
      "perSessionCapUsd": 5.00
    }
  ]
}

Auth modes

The authMode axis corresponds to how the LLM API key is supplied:

authMode	Key source
`byok`	Organisation supplies its own API key (Bring Your Own Key)
`metered`	Rensei's metered billing key - usage charged through Rensei
`shared`	Pooled key shared across tenants (platform-default)
`host-session`	Key from the host daemon's local credential socket
`local`	Local daemon, no external API calls

Each auth mode has different cost-responsibility implications. byok and host-session spend from the customer's own key; metered and shared spend from Rensei's key and are invoiced.

API reference

# Get cost events for an org (paginated)
GET /api/admin/billing/spend?orgId=<id>&window=30d

# Get the current cap policy for an org
GET /api/admin/billing/cap-policy/<orgId>

# Update the cap policy
PATCH /api/admin/billing/cap-policy/<orgId>

Agent Cards - billing_class is derived from the card's auth config
LLM Auth Modes - full description of each auth mode
Model Catalog & Routing - where pricing rows live

On this page