Cost and attribution

How members and teams apply virtual-key controls, attribute spend and usage, and enforce ceilings for quota governance.

Nobody can answer “who spent what, on which model” when every caller shares the same provider key. Members and teams give every caller an attributable identity and virtual-key controls on every surface where attribution is turned on. Resilience and caching →

Member

A Member is a registered caller: a person or client that reaches models through the appliance. A Member is distinct from a User, who signs in to administer the appliance. A Member acts as a virtual key, carrying a model allow-list, per-minute request and token limits, and monthly ceilings, plus stable attribution metadata across every Surface it calls.

A Member's Caps & Limits tab, showing its monthly Budget and Token cap, per-minute Requests and Tokens limits, and Allowed models

Virtual key

A Virtual Key is the effective set of controls attached to a Member: its model allow-list, rate limits, monthly ceilings, and stable identity for attribution. Because attribution is surface-type-agnostic, a Member’s Virtual Key applies consistently across LLM and IDE Surfaces.

How spend and quotas roll up to a Team

A Team is a group of Members. Once a Surface is configured to contribute to team quotas, spend, tokens, and rate-limit activity are attributed to both the Member and its Team, aggregated across every eligible Surface the Member calls. Surfaces can be restricted to specific Teams, and Team-level ceilings apply in addition to Member-level ceilings.

A team’s member list sits on its own Members tab; its spend and token ceilings sit on a separate Caps & Limits tab of the same page:

A Team's Caps & Limits tab, showing its team-wide Budget and Token cap
Surface A · Surface B · Surface C
→
Member
→
Team

Restricting surfaces to teams

A surface can be restricted to specific Teams, so only their Members may call it. The built-in Anonymous Member and Anonymous Team provide open access when a Surface accepts unauthenticated traffic. An administrator can tighten that default by enabling or disabling those built-ins instead of reconfiguring every Surface.

The member and team model is surface-type-agnostic: any future surface type inherits attribution without additional work.

How a request is resolved to a Member

Attribution resolves a request to a Member and its Team or Teams for spend and quota accounting. Each Surface chooses the caller-match source: a request header, JWT claim, body path, mTLS attribute, or API-key binding.

Managing Members

Administrators manage Members separately from dashboard Users. A Member is a runtime caller, not an account that signs in to operate the appliance. It can represent a person, application, or automated system and can have one or more identifiers for caller matching.

Member controls include Monthly Budget (USD), Monthly Token Cap, Requests Per Minute, Tokens Per Minute, and Allowed Models. These controls travel with the Member across every eligible Surface it calls. Administrators can create, edit, disable, and delete Members. Disabling a Member blocks matching callers while preserving its record and usage history. Deleting a Member removes it from active listings and attribution, while historical usage remains attributable through its tombstoned record. See the Members reference → for identifier matching, auto-provisioning, and field-level details.

Managing Teams

Administrators use Teams to group Members for combined spend, token usage, and access control. A Member can belong to more than one Team. Team-wide caps apply to the combined usage of the Team’s Members, while Member caps remain attached to the individual caller.

Surface participation is configured through the team-attribution controls. Surface use contributes to team quotas enables attribution for that Surface. Caller identity is read from (first match wins) defines the ordered sources used to identify the caller. Restrict surface to teams limits access to selected Teams. Enforce team / member limits (block at 429) determines whether reached limits block requests or usage is recorded for reporting only. See the Teams reference → for the team record, surface controls, and gate behaviour.

Team Gate resolution

On a Surface with team attribution enabled, the Team Gate resolves and checks each request in order:

  1. It reads the caller identity from the configured sources and resolves a Member.
  2. If verified auto-provisioning is enabled, it can create a Member for an unrecognised verified caller. Otherwise, it falls back to the built-in anonymous Member.
  3. It resolves the Member’s enabled Teams, falling back to the anonymous Team when no enabled Team applies.
  4. It checks Member and Team access, including Restrict surface to teams.
  5. It checks the Member’s Allowed Models list.
  6. When enforcement is enabled, it checks per-minute Member limits and monthly Member and Team ceilings.
  7. After an allowed request completes, it records the request, tokens, and spend against the relevant Member and Teams.

Access or model allow-list failures return 403. Enforced rate and quota limits return 429. When team attribution is disabled, the Team Gate does not apply these checks, although other surface governance can still run.

Usage and chargeback exports

Attributed cost, token usage, and latency can be analysed by Surface, stage, Member, and Team. Per-stage accounting includes the LLM, Judge, Jury, Decider, and configured Expert Witness stages, so teams can separate model spend from governance-stage spend. See Cost and usage governance → and Observability →.

Chargeback reports can be exported as JSON or CSV for a selected date range and rolled up by Team, Member, and Surface. This supports departmental or customer chargeback without reducing shared Surface usage to one undifferentiated total.

Monthly ceiling

A Monthly Ceiling is a USD budget or token cap enforced at the Member, Team, Surface, or pipeline-stage level. Once a ceiling is reached, further requests are rejected with 429.

Cost spike

A Cost Spike is a rolling anomaly: an execution whose cost is far above the recent mean for its Surface. Cost-spike alerts send notifications through configured integrations before the monthly bill arrives.

Provider-side cache tokens

Provider-side prompt-cache tokens are the vendor-reported cached-token counts, such as OpenAI cached_tokens, Anthropic cache_read_input_tokens, and DeepSeek prompt_cache_hit_tokens. Agent Stream surfaces these separately from its own response cache, so operators can distinguish provider-side cache-hit economics from responses served directly by Agent Stream.

Why this matters

Attribution is what turns cost and usage governance, described in Cost and usage governance →, into per-team and per-customer accountability rather than one shared number for the whole appliance. It is also the foundation for multi-tenant governance, where different teams or customers need separately enforced quotas on the same shared surfaces.