# Usage Commands > See [Usage module docs](../../modules/usage) for permissions and data model. # Usage Commands See [Usage module docs](../../modules/usage) for permissions and data model. ### `soat list-usage-meters` List usage meters - Method: `GET` - Path: `/api/v1/usage/meters` #### Usage ```bash 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 ```bash soat get-usage --project-id --group-by ``` #### 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 ```bash 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 ```bash soat create-usage-threshold --project-id --metric --window --threshold ``` #### 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 ```bash soat delete-usage-threshold --threshold-id ``` #### 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 ```bash 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 ```bash 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 ```bash soat upsert-price-book --prices > ``` #### Options ##### `--prices` — - Source: `body` - Required: yes - Type: `array`