opschain agents usage

packs:ai-agents

opschain agents usage [--project <code>] [--agent <code>] [--since 30d] [--until <when>]
                      [--grain day] [--by agent|provider|model|project|grant] [--timezone <zone>]
                      [-o json|yaml|csv] [--server <url>] [--auth-token <token>]
opschain agents usage --recommend-caps --grant <id> [--headroom 1.5] [--all-windows] [--propose] [--note <text>]

Shows model-token usage (v2 ModelUsageService.SummarizeModelUsage): every brokered model call is metered into a UTC minute bucket keyed on the model the provider's response reported and rolled up hourly, daily, weekly, monthly, quarterly and yearly on the estate's reporting calendar (usage.timezone / usage.fiscal_year_start, with a project override). Tokens and calls, never money: the CSV is what a finance model prices itself (opschain docs provider-usage).

Without --project the whole estate is read, which needs read on the root; with it, read on the project (a project you may not read is reported as unknown).

Flags

Flag	Meaning
--project <code>	Project code to read. Default: the whole estate.
--agent <code>	Narrow the rows to one agent code.
--since <when>	Window start: a relative age (30d, 2w, 12h), an RFC 3339 instant or a YYYY-MM-DD date (UTC midnight). Default 30d.
--until <when>	Window end, same forms. Default: now.
--grain <grain>	minute, hour, day (default), week, month, quarter or year. Minute buckets are UTC; every other grain is a bucket on the calendar the rows were rolled under.
--by <dimension>	Group each bucket's rows by agent, provider, model, project or grant. Default: one total row per bucket.
--timezone <zone>	IANA zone the bucket labels are rendered in. Default: the project's reporting zone. Bucket boundaries never move.
--recommend-caps	Instead of usage, propose a token cap for every window --grant carries, from its observed per-bucket distribution: p95 × --headroom, rounded up, never below the observed peak while fewer than twenty buckets were seen.
--grant <id>	The trust grant --recommend-caps measures (opschain admin trust list). Required with it.
--headroom <n>	The multiplier on the observed p95. Default 1.5; below 1 is refused.
--all-windows	With --recommend-caps: propose all six windows, not only the ones the grant carries.
--propose	With --recommend-caps: raise a replacement grant — the measured grant's subject, scope, actions, tier, act-as and other caps with the recommended token caps — through POST /api/trust/grants, the same approval funnel opschain admin trust grant rides. Needs the admin credential ladder.
--note <text>	Audit note stored on the proposed grant (with --propose); the grant it replaces is always named.
--server <url>	Server base URL. Default: the active context, then OPSCHAIN_SERVER.
--auth-token <token>	Bearer token override. Default: your opschain login session, then $OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login for that server.

Output

The table lists one row per bucket (and group): BUCKET (the label in the rendering zone), the grouped dimension, CALLS, IN, OUT, TOTAL (input + output — the figure the caps meter), REFUSED (calls a cap refused pre-flight) and PEAK/MIN (the busiest minute inside the bucket), followed by a totals line that also counts the cap-approaching warnings and names the calendar.

-o json / -o yaml carry since, until, grain, group_by, timezone, calendar (timezone, fiscal_year_start), totals (calls, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, total_tokens, refused_calls, approaching_count) and rows (opschain docs resources/model_usage).

-o csv prints the export instead (ExportModelUsage): one row per bucket and full tuple (provider, kind, model, project, agent, grant) with the calendar columns, --by ignored, rows rolled under a previous calendar included and flagged calendar_superseded.

With --recommend-caps the table is one row per window — WINDOW, CURRENT, OBSERVED (the sum over the buckets), PEAK, P95, SAMPLES, RECOMMENDED — and -o json carries grant, since and recommendations; with --propose the stored replacement grant is added as proposed_grant and the human output names the measured grant to revoke once the replacement is active (every applying grant's caps are enforced, so the old caps keep biting until it is).

Exit codes

Code	Meaning
0	The usage (or the recommendation) was printed; with --propose, the grant was stored.
1	The server refused or failed the request (an unreadable project, an unknown grant, a rejected credential, a refused proposal).
2	Usage — a malformed --since/--until, --propose without --recommend-caps, --recommend-caps without --grant, or no server / credential resolvable.

Named errors

• invalid --since "<value>": expected a relative age (30d, 2w, 12h), an RFC 3339 instant or a YYYY-MM-DD date — exit 2.
• --propose needs --recommend-caps — exit 2.
• --recommend-caps names the grant to measure with --grant <id> (list grants with 'opschain admin trust list') — exit 2.
• nothing to propose: the grant carries no token-cap window (pass --all-windows) — exit 1.
• grain must be minute, hour, day, week, month, quarter or year / group_by must be agent, provider, model, project or grant / timezone is not an IANA time zone name / since must be before until — the server's field violations, exit 1.
• headroom must be at least 1 — exit 1.
• a server is required — pass --server <url>, set OPSCHAIN_SERVER, or 'opschain context use <name>' — exit 2.
• the server rejected the credential — run 'opschain login' again, or check the admin token — exit 1.

Examples

Daily tokens by agent for a project over the last month:

opschain agents usage --project limebank --by agent

The last hour minute by minute, by model, labelled in Adelaide time, as CSV:

opschain agents usage --project limebank --since 1h --grain minute --by model \
  --timezone Australia/Adelaide -o csv > tokens.csv

Measure a grant and propose caps with 2× headroom through the funnel:

opschain agents usage --recommend-caps --grant octg_01J… --headroom 2 --propose \
  --note "caps from the first fortnight's usage"

Related settings

• usage.timezone, usage.fiscal_year_start — the reporting calendar (project override).
• usage.minute_retention, usage.hour_retention — how far back minute and hour grains reach.
• model_usage.cap_warning_fraction — when warn:trust:cap_approaching fires.

See also

• opschain docs provider-usage — the component page (the model lane and every other provider family).
• opschain docs cli/admin-trust-grant — the six cap flags.
• opschain docs cli/admin-agent-trust-review — observed-versus-cap per window on one agent.