Skip to main content

Usage Commands

See Usage module docs for permissions and data model.

soat list-usage-meters​

List usage meters

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

Usage​

soat list-usage-meters

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. An actor that does not exist in scope yields an empty page.

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

Filter by the session the usage was produced in. A session that does not exist in scope yields an empty page.

  • 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
--meter-type​

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

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

Filter by what the spend was incurred for. eval is an eval run's item generations and eval_judge an llm_judge scorer's own completion, so verification spend is source in (eval, eval_judge). Ordinary agent traffic carries no source and is matched by neither.

  • Source: query
  • Required: no
  • Type: string
  • Example: eval
--limit​

—

  • Source: query
  • Required: no
  • Type: integer
  • Default: 50
--offset​

—

  • Source: query
  • Required: no
  • Type: integer
  • Default: 0

soat get-usage​

Get aggregated usage for a project

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

Usage​

soat get-usage --project-id <string> --group-by <enum("model", "ai_provider", "agent", "run", "day", "meter_type", "actor", "session", "source")>

Options​

--project-id​

Project public ID to aggregate usage for

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

Dimension to bucket by. 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.

  • Source: query
  • Required: yes
  • Type: enum("model", "ai_provider", "agent", "run", "day", "meter_type", "actor", "session", "source")
--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). Omit to include every meter. An unknown type yields an empty rollup, not an error.

  • 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
--limit​

Maximum number of results to return

  • Source: query
  • Required: no
  • Type: integer
  • Default: 50
--offset​

Number of results to skip

  • Source: query
  • Required: no
  • Type: integer
  • Default: 0

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 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>