Skip to main content

Usage Commands

See Usage module docs for permissions and data model.

soat list-usage-events​

List usage events

  • Method: GET
  • Path: /api/v1/usage/events

Usage​

soat list-usage-events

Options​

--agent-id​

Filter by agent public ID

  • Source: query
  • Required: no
  • Type: string
--generation-id​

Filter by generation public ID

  • Source: query
  • Required: no
  • Type: string
--trace-id​

Filter by trace public ID

  • Source: query
  • Required: no
  • Type: string
--actor-id​

Filter by the actor (end user) the usage is attributed to.

  • Source: query
  • Required: no
  • Type: string
--session-id​

Filter by the session the usage was produced in.

  • Source: query
  • Required: no
  • Type: string
--ai-provider-id​

Filter by the provider record the spend was billed against.

  • Source: query
  • Required: no
  • Type: string
--orchestration-run-id​

Filter by the orchestration run that metered the event.

  • Source: query
  • Required: no
  • Type: string
--orchestration-id​

Filter by orchestration — the events of the runs it started itself, not the subtree its loop or sub_orchestration nodes started. An orchestration that does not exist in scope yields an empty page.

  • Source: query
  • Required: no
  • Type: string
--model​

Filter by the as-billed SKU the event recorded. Matched as recorded, so it still selects events whose provider has since been deleted.

  • Source: query
  • Required: no
  • Type: string
--trigger-id​

Filter by the trigger that initiated the generation

  • Source: query
  • Required: no
  • Type: string
--action-id​

Filter by logical action id

  • Source: query
  • Required: no
  • Type: string
--tool-id​

Filter by the tool a tool_execution event metered, including a tool another project shares with one in scope.

  • Source: query
  • Required: no
  • Type: string
--publisher-project-id​

Filter to the calls made through a share of a resource the named project owns.

  • Source: query
  • Required: no
  • Type: string
--outcome​

Filter by how a tool_execution call ended: ok, error or timeout. Every other meter carries no outcome and is matched by none of them.

  • Source: query
  • Required: no
  • Type: string
--meter-type​

Filter by meter type (e.g. llm_tokens, compute_execution, api_request, storage, tool_execution)

  • Source: query
  • Required: no
  • Type: string
--source​

Filter by what the spend was incurred for. eval is an eval run's item generations, eval_judge an llm_judge scorer's own completion and eval_scorer a tool scorer's call, so verification spend is source in (eval, eval_judge, eval_scorer); decider is a decision's evaluation; embedding is any embedding call. Ordinary agent traffic carries no source and is matched by none of them.

  • Source: query
  • Required: no
  • Type: string
  • Example: eval

soat get-usage-aggregate​

Get aggregated usage for a project

  • Method: GET
  • Path: /api/v1/usage/aggregate

Usage​

soat get-usage-aggregate --project-id <string>

Options​

--project-id​

Project public ID to aggregate usage for

  • Source: query
  • Required: yes
  • Type: string
--group-by​

Dimension to bucket by. Omit it to skip bucketing entirely: totals still describes the whole window and groups is an empty page, which is what "what did this one thing cost" wants. A value naming no dimension is a 400. day buckets on the event's UTC calendar day; the others bucket on the matching column. ai_provider buckets on the provider the spend was billed against — a routed generation's serving target, or the agent's pinned provider. model buckets on the model id and the provider that served it, so one model name served by two providers is two groups (see ai_provider_id). source buckets by what the spend was incurred for (eval, eval_judge), which is how verification spend is priced apart from the traffic serving real users; unlabelled traffic collapses into the single null bucket. orchestration_run buckets on the orchestration run the event belongs to — a standalone generation runs no orchestration and collapses into the single null bucket, so the bucket count under this dimension is not a count of runs.

  • Source: query
  • Required: no
  • Type: enum("model", "ai_provider", "agent", "orchestration_run", "day", "meter_type", "actor", "session", "source", "tool")
--include​

Optional extras to compute. The only value is distinct, which adds totals.distinct — one distinct-entity count per attribution column. It is opt-in because each key costs the database one extra sort of the window, so the default response keeps its cost whatever the event table grows to carry; a caller counting entities sends one request at limit=1&include=distinct. Any other value is a 400.

  • Source: query
  • Required: no
  • Type: enum("distinct")
--from​

Inclusive lower bound (ISO-8601 timestamp) on the event created_at. Omit for no lower bound.

  • Source: query
  • Required: no
  • Type: string
--to​

Inclusive upper bound (ISO-8601 timestamp) on the event created_at. Omit for no upper bound.

  • Source: query
  • Required: no
  • Type: string
--meter-type​

Narrow the rollup to one meter type (e.g. llm_tokens, compute_execution, api_request, storage, tool_execution). Omit to include every meter. An unknown type yields an empty rollup, not an error.

  • Source: query
  • Required: no
  • Type: string
--session-id​

Narrow the whole rollup — every bucket, totals and totals.distinct alike — to one session's traffic. Combines with group_by: group_by=day&session_id=… is a conversation's spend per day, group_by=model is the same spend split by model. Like every id narrowing it matches the id the event recorded, so a deleted session's spend stays selectable; an id no event in this project recorded yields an empty rollup, never the project total.

  • Source: query
  • Required: no
  • Type: string
--actor-id​

The same narrowing, for one end user across every session they appear in. This is the figure behind a scope: actor, metric: cost_usd quota — what that actor has spent, against the cap it is held to.

  • Source: query
  • Required: no
  • Type: string
--agent-id​

Narrow to one agent's traffic, across every session, run and trigger that dispatched it.

  • Source: query
  • Required: no
  • Type: string
--ai-provider-id​

Narrow to the spend billed against one provider record — a routed generation's serving target, or the agent's pinned provider.

  • Source: query
  • Required: no
  • Type: string
--orchestration-run-id​

Narrow to the events one orchestration run metered.

  • Source: query
  • Required: no
  • Type: string
--orchestration-id​

Narrow to the runs of one orchestration — the runs it started itself, never the subtree a loop or sub_orchestration node started under it, which is metered against the child orchestration where it was incurred. Additive: summed across a project's orchestrations the figures reach the project total exactly once. For the subtree figure of a single invocation, read usage on the run.

  • Source: query
  • Required: no
  • Type: string
--generation-id​

Narrow to one generation's events. A generation writes more than one when it meters several dimensions (tokens and compute).

  • Source: query
  • Required: no
  • Type: string
--trace-id​

Narrow to the events recorded under one trace.

  • Source: query
  • Required: no
  • Type: string
--model​

Narrow to one model, matched against the as-billed SKU the event recorded. A value naming no model yields an empty rollup, not an error. Under group_by=model this is a single-bucket rollup; under any other dimension it is that model's spend split by the dimension.

  • Source: query
  • Required: no
  • Type: string
--source​

Narrow by what the spend was incurred for — eval and eval_judge are verification spend, decider is decision spend. Ordinary traffic carries no source, so it cannot be selected by this filter; omit the filter for everything.

  • Source: query
  • Required: no
  • Type: string
--trigger-id​

Narrow to the spend one trigger initiated. Matched as recorded rather than resolved, so it still selects the spend of a trigger that has since been deleted.

  • Source: query
  • Required: no
  • Type: string
--action-id​

Narrow to one caller-supplied action label, for per-action spend. Matched as recorded, like trigger_id.

  • Source: query
  • Required: no
  • Type: string
--tool-id​

Narrow to the executions of one tool, including one another project shares with this one.

  • Source: query
  • Required: no
  • Type: string
--publisher-project-id​

Narrow to the calls made through a share of a resource the named project owns.

  • Source: query
  • Required: no
  • Type: string
--outcome​

Narrow tool_execution events by how the call ended — ok, error or timeout — matched as recorded. outcome=error is a tool's failures without a second meter.

  • Source: query
  • Required: no
  • Type: string

soat list-usage-thresholds​

List usage thresholds

  • Method: GET
  • Path: /api/v1/usage/thresholds

Usage​

soat list-usage-thresholds

Options​

--project-id​

Filter by project public ID

  • Source: query
  • Required: no
  • Type: string

soat create-usage-threshold​

Create a usage threshold

  • Method: POST
  • Path: /api/v1/usage/thresholds

Usage​

soat create-usage-threshold --project-id <string> --metric <enum("cost_usd", "tokens")> --window <enum("calendar_month", "rolling_24h")> --threshold <number>

Options​

--project-id​

—

  • Source: body
  • Required: yes
  • Type: string
--metric​

—

  • Source: body
  • Required: yes
  • Type: enum("cost_usd", "tokens")
--window​

—

  • Source: body
  • Required: yes
  • Type: enum("calendar_month", "rolling_24h")
--threshold​

Must be greater than 0

  • Source: body
  • Required: yes
  • Type: number

soat delete-usage-threshold​

Delete a usage threshold

  • Method: DELETE
  • Path: /api/v1/usage/thresholds/{threshold_id}

Usage​

soat delete-usage-threshold --threshold-id <string>

Options​

--threshold-id​

Threshold public ID

  • Source: path
  • Required: yes
  • Type: string

soat get-usage-receipt​

Get a generation or orchestration-run billing receipt

  • Method: GET
  • Path: /api/v1/usage/receipt

Usage​

soat get-usage-receipt

Options​

--generation-id​

Generation public ID. Mutually exclusive with orchestration_run_id.

  • Source: query
  • Required: no
  • Type: string
--orchestration-run-id​

Orchestration run public ID. Returns the receipt summed across every generation the run metered. Mutually exclusive with generation_id.

  • Source: query
  • Required: no
  • Type: string

soat get-price-book​

Get the price book

  • Method: GET
  • Path: /api/v1/usage/prices

Usage​

soat get-price-book

Options​

This command has no options.

soat upsert-price-book​

Upsert price-book rows

  • Method: PUT
  • Path: /api/v1/usage/prices

Usage​

soat upsert-price-book --prices <array<object>>

Options​

--prices​

—

  • Source: body
  • Required: yes
  • Type: array<object>