Model usage and provider usage

packs:ai-agents

The usage telemetry's read shapes, served by the v2 ModelUsageService. The model lane — one row per token bucket and group, the totals over a window, the cap recommendations from the observed distribution — through SummarizeModelUsage, ExportModelUsage (CSV) and RecommendCaps, which need read on the project path (404-on-deny), read on the root for the estate. The provider lane every family shares — one row per bucket, provider and metric, and the overview of every registered provider — through ListProviderUsage and ListProvidersOverview, which sit behind the provider-record administrator's verdict. Facts only — no price, cost or currency (opschain docs provider-usage).

ModelUsageRow

One bucket of one group: a minute row straight off the UTC table, or a rolled-up bucket on the calendar it was rolled under.

Field	Type	Meaning
agent_code	string	The agent's code (filled when grouped by agent; always on an export).
bucket_end	timestamp	The first instant after the bucket.
bucket_label	string	The bucket start rendered in the response's timezone (RFC 3339 with its offset) — the label a table or chart shows.
bucket_start	timestamp	The bucket's start instant (UTC on the wire).
cache_creation_tokens	integer/string	Prompt-cache creation tokens the provider reported; recorded, never metered against a cap.
cache_read_tokens	integer/string	Prompt-cache read tokens the provider reported; recorded, never metered.
calendar_superseded	boolean	True on an exported row rolled under a previous calendar; a summary never includes one.
calls	integer/string	Served calls in the bucket.
fiscal_year_start	string	The MM-DD fiscal year start the row was rolled under (empty on minute rows).
grain	string	minute, hour, day, week, month, quarter or year.
grant_id	string	The most specific token-capped grant the calls were attributed to; empty when no cap applied.
input_tokens	integer/string	Input (prompt) tokens.
max_call_tokens	integer/string	The largest single call in the bucket (input + output).
model	string	The model the provider's response reported (the request's model when the response named none).
output_tokens	integer/string	Output (completion) tokens.
peak_day_tokens	integer/string	The busiest day's total inside a week row or coarser.
peak_hour_tokens	integer/string	The busiest hour's total inside a day row or coarser.
peak_minute_tokens	integer/string	The busiest minute's total inside an hour row or coarser (a minute row's own total).
project_path	string	The project the agent is enrolled in (/code).
provider_code	string	The model provider record's code.
provider_kind	string	The model provider record's kind (anthropic, openai, azure-openai, openai-compatible), resolved from the registry by the row's code; empty when the row is not grouped by provider.
refused_calls	integer/string	Calls refused pre-flight by a token-cap window; they spent nothing.
timezone	string	The IANA zone the row was rolled under (empty on minute rows).
total_tokens	integer/string	input_tokens + output_tokens — the figure the caps meter.

ModelUsageTotals

The sums over a summary's rows.

Field	Type	Meaning
approaching_count	integer/string	How many (grant, window, period) cap-approaching warnings fired for the grants the rows carry, over periods still within the counter retention.
cache_creation_tokens	integer/string	Sum of the rows' cache-creation tokens.
cache_read_tokens	integer/string	Sum of the rows' cache-read tokens.
calls	integer/string	Sum of served calls.
input_tokens	integer/string	Sum of input tokens.
output_tokens	integer/string	Sum of output tokens.
refused_calls	integer/string	Sum of refused calls.
total_tokens	integer/string	Sum of total_tokens.

The summary response also carries since, until, grain, group_by, timezone (the zone the labels were rendered in) and the project's reporting calendar as calendar_timezone / calendar_fiscal_year_start. The export response is csv (one header row, then one row per bucket and tuple with the same columns as ModelUsageRow) and row_count.

CapRecommendation

One window's proposed cap and the figures behind it (RecommendCaps), answered beside the measured TrustGrant and the since the history was read from.

Field	Type	Meaning
current_cap	integer/string	The grant's cap on this window today; zero when unset.
headroom	number	The multiplier applied to the p95 (1.5 by default).
observed_p95	integer/string	The p95 of the window's per-bucket totals (nearest rank).
observed_peak	integer/string	The busiest bucket's total.
observed_total	integer/string	The sum over the observed buckets.
recommended_cap	integer/string	p95 × headroom, rounded up — never below the peak while fewer than twenty buckets were seen.
samples	integer	How many buckets were observed.
window	string	minute, day, week, month, quarter or year.

ProviderUsageRow

One bucket of one provider's one metric (ListProviderUsage): a minute row straight off the UTC table, or a rolled-up bucket on the calendar it was rolled under. The request names the family (kind: secrets, transport, model, image_build, image_registry, identity, siem, otlp, github or jsm), optionally one code, the grain, the window (from, to), optionally one metric, one extra group_by dimension (project, detail, agent, grant), a project_code and the label timezone.

Field	Type	Meaning
agent_code	string	The agent's code (filled when grouped by agent; the model lane only).
bucket_end	timestamp	The first instant after the bucket.
bucket_label	string	The bucket start rendered in the response's timezone (RFC 3339 with its offset).
bucket_start	timestamp	The bucket's start instant (UTC on the wire).
count	integer/string	Samples in the bucket — a counter's count.
detail	string	What the family records as its detail (the model a call reported, the image a push carried); filled when grouped by detail.
errors	integer/string	The samples that failed (a failure metric's count lands here too).
fiscal_year_start	string	The MM-DD fiscal year start the row was rolled under (empty on minute rows).
grain	string	minute, hour, day, week, month, quarter or year.
grant_id	string	The token-capped grant the calls were attributed to (filled when grouped by grant; the model lane only).
latency_max_ms	integer/string	The slowest single sample, where the seam times the call.
latency_sum_ms	integer/string	The summed latency, where the seam times the call.
metric	string	The metric the row counts (opschain docs provider-usage, "The families and their metrics").
peak_day_value	integer/string	The busiest day's value inside a week row or coarser.
peak_hour_value	integer/string	The busiest hour's value inside a day row or coarser.
peak_minute_value	integer/string	The busiest minute's value inside an hour row or coarser (a minute row's own value).
project_path	string	The project the call was made for (filled when grouped by project or agent); empty on platform-level rows.
provider_code	string	The provider record's code.
provider_kind	string	The family.
value_max	integer/string	The largest single sample (a value metric's quantity; a gauge's highest reading).
value_sum	integer/string	The summed value — a counter's count, a value metric's quantity (tokens, bytes, seconds).

ProviderUsageMetricTotal

One per metric the family registers (zero when nothing was recorded), summing the response's rows.

Field	Type	Meaning
count	integer/string	Sum of count.
errors	integer/string	Sum of errors.
latency_max_ms	integer/string	The slowest sample over the window.
latency_sum_ms	integer/string	Sum of latency_sum_ms.
metric	string	The metric.
metric_kind	string	count, value or gauge — how the metric's value reads.
value_max	integer/string	The largest sample over the window.
value_sum	integer/string	Sum of value_sum.

The response also carries from, to, grain, group_by, timezone (the zone the labels were rendered in), the reporting calendar as calendar_timezone / calendar_fiscal_year_start and, when the request names one model provider whose record carries a provider-level model budget, token_budget — one ProviderTokenBudgetWindow per window with a ceiling.

ProviderTokenBudgetWindow

One window of a model provider's provider-level model budget at the instant of the read (opschain docs model-providers): the ceiling the record sets, the shared counter's spend across every agent and every call through the provider, what remains, and the window's local boundaries on the estate's reporting calendar. Carried by ListProviderUsage (token_budget) and by a model provider's ProviderOverviewRow.

Field	Type	Meaning
cap	integer/string	The ceiling the provider record sets on this window.
fraction	number	used / cap.
remaining	integer/string	cap - used, never below zero.
resets_at	timestamp	The first instant after the window — when the counter starts over (the sliding minute: one minute after the read).
used	integer/string	The tokens spent in the window so far, across every agent and call through the provider.
window	string	minute, day, week, month, quarter or year.
window_start	timestamp	The window's start instant.

ProviderOverviewRow

One registered provider on the overview (ListProvidersOverview), answered beside today_start (the reporting calendar's local midnight), computed_at and calendar_timezone.

Field	Type	Meaning
code	string	The provider record's code.
display_name	string	The record's display name.
enabled	boolean	Whether the record is enabled.
gauges	map	The family's gauges' current readings keyed by metric (backlog_depth, rate_limit_remaining); absent until first observed.
health_checked_at	timestamp	When the health was last established (the test verb's run; a SIEM connection's last delivery).
health_error	string	The last probe's failure; empty while healthy. Never credential material.
health_status	string	healthy, unhealthy or unknown (never probed, or the family keeps no probe) — the health probe's last result, never a metric.
kind	string	The family.
metrics	string[]	The metrics the family records, so a page can show the full set.
provider_kind	string	The record's own kind within its family (anthropic, openbao, ssh-ca, splunk_hec …); empty where the family has one shape.
today_count	integer/string	The family's primary metric's count since today_start.
today_errors	integer/string	The errors across every metric since today_start.
token_budget	ProviderTokenBudgetWindow[]	A model provider's provider-level model budget at the instant of the read — one entry per window the record sets a ceiling on; empty for every other family and for a provider with no ceiling.

From the CLI

opschain agents usage (opschain docs cli/agents-usage) renders the model summary as a table, -o json as this document, -o csv as the export; --recommend-caps --grant <id> prints the recommendations and --propose raises the replacement grant through the approval funnel. opschain admin providers usage and opschain admin providers overview (opschain docs cli/admin-providers) render the provider rows and the overview.

Related pages

• opschain docs provider-usage — the component page: the families, the buckets, the calendar, the six windows.
• opschain docs resources/trust — the grant's tokens_per_* fields.
• opschain docs settings-reference — the usage.* settings.