Skip to main content

Quotas Commands

See Quotas module docs for permissions and data model.

soat list-quotas​

List quotas

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

Usage​

soat list-quotas

Options​

--project-id​

Project ID (required if not using project key auth)

  • Source: query
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--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-quota​

Create a quota

  • Method: POST
  • Path: /api/v1/quotas

Usage​

soat create-quota --scope <enum("project", "api_key", "agent", "actor")> --metric <enum("requests", "tokens", "cost_usd", "storage_bytes")> --window <enum("rolling_1m", "rolling_1h", "rolling_24h", "calendar_month", "current")> --limit <number>

Options​

--project-id​

Project ID (required if not using project key auth)

  • Source: body
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--scope​

The scope the quota applies to

  • Source: body
  • Required: yes
  • Type: enum("project", "api_key", "agent", "actor")
--scope-ref​

Public id of the api key / agent / actor the quota applies to. For api_key and agent scope, NULL means all entities of that scope type in the project. For actor scope, NULL means one budget per actor — each end user gets their own allowance — rather than a pooled total across all actors.

  • Source: body
  • Required: no
  • Type: string \| null
  • Example: key_V1StGXR8Z5jdHi6B
--metric​

The metric being capped

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

The window over which the metric is aggregated. current is the only accepted value for storage_bytes (a stored total is not aggregated over time) and is refused for every other metric.

  • Source: body
  • Required: yes
  • Type: enum("rolling_1m", "rolling_1h", "rolling_24h", "calendar_month", "current")
--limit​

The cap. Must be a positive integer for requests/tokens/storage_bytes (bytes); fractional values are allowed for cost_usd.

  • Source: body
  • Required: yes
  • Type: number
  • Example: 600
--mode​

enforce blocks with 429 (requests at the middleware, tokens/cost_usd at the pre-generation check); monitor observes without blocking — a breach fires the quota.exceeded webhook and writes a quotas:MonitorBreach audit entry, but the request is let through.

  • Source: body
  • Required: no
  • Type: enum("enforce", "monitor")
  • Default: enforce
  • Example: enforce
--on-unpriced​

Only for metric cost_usd (400 on any other metric). What an enforce quota does when the current window is a pricing blackout — several metered llm_tokens events, none of them priced, so the aggregate is 0 however much was actually spent. Platform meters such as compute_execution are read for the aggregate but never for this verdict. block (the default) refuses new generations with 409 QUOTA_UNENFORCEABLE until pricing is configured; allow accepts the unmeasurable spend explicitly. Either way a quota_unpriced exception is filed. monitor-mode quotas never block regardless. A partly priced window is not a blackout: no posture refuses it, it is enforced on its priced total, and it files the same exception.

  • Source: body
  • Required: no
  • Type: enum("block", "allow")
  • Default: block
  • Example: block
--meter-type​

Only for metric cost_usd (400 on any other metric). The meter this cap answers for. Omit it and the cap sums every priced meter, which is the existing behaviour; name one and only that meter's cost counts, so an AI spend cap is not consumed by platform meters the operator prices (and vice versa). Part of the quota's identity, so two meter scopes can share a scope/metric/window and neither conflicts with an unscoped cap. Immutable after creation — replace the quota to change it.

  • Source: body
  • Required: no
  • Type: enum("llm_tokens", "compute_execution", "api_request", "storage")

soat get-quota​

Get a quota

  • Method: GET
  • Path: /api/v1/quotas/{quota_id}

Usage​

soat get-quota --quota-id <string>

Options​

--quota-id​

Quota ID

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

soat update-quota​

Update a quota

  • Method: PATCH
  • Path: /api/v1/quotas/{quota_id}

Usage​

soat update-quota --quota-id <string>

Options​

--quota-id​

Quota ID

  • Source: path
  • Required: yes
  • Type: string
--limit​

New limit

  • Source: body
  • Required: no
  • Type: number
  • Example: 1000
--mode​

New mode

  • Source: body
  • Required: no
  • Type: enum("enforce", "monitor")
  • Example: monitor
--on-unpriced​

New pricing posture. Only for metric cost_usd (400 on any other metric); see the create operation for what block and allow mean.

  • Source: body
  • Required: no
  • Type: enum("block", "allow")
  • Example: allow

soat delete-quota​

Delete a quota

  • Method: DELETE
  • Path: /api/v1/quotas/{quota_id}

Usage​

soat delete-quota --quota-id <string>

Options​

--quota-id​

Quota ID

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