> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domesystems.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quotas

> Cap governed LLM spend across workspaces, agents, Gateways, pools, and models

export const quota = "A Quota caps governed LLM spend in USD over a daily or monthly window for a workspace, agent, Gateway, pool, or model. Dome rejects or reroutes metered calls when the budget is exhausted.";

<p>
  {quota}
</p>

## Overview

The gateway meters token usage on completed calls, prices it at per-model rates, updates spend for the window, and enforces every applicable Quota. Limit changes reach the gateway on the next config sync. Refer to [Quotas](/concepts/controls/quotas#when-a-quota-change-takes-effect) concept for how that differs from spend accrual.

Quotas are workspace-scoped records. Each Quota has a subject, a USD limit, a reset window, an optional name, and an enabled flag. Subject identity is fixed at create time. Create is insert-only for each subject identity and window pair. Disabled Quotas remain listed but are not enforced.

The typical workflow is:

1. [Set a Quota](#set-a-quota) for the subject that owns the budget.
2. Optionally [set a Gateway Quota](#set-a-gateway-quota) when spend should follow a gateway.
3. [Update](#update-a-quota), [list](#list-quotas), or [remove](#remove-a-quota) Quotas as budgets change.

## Requirements

Before you begin:

* Authenticate to Dome and select a workspace
* Have the subject already configured (agent, model, pool, Gateway, or a subject verified via [Delegated agents](/connect/agents/delegated) as needed)
* Use a plan that allows cost Quotas for the workspace. Cost Quotas are included on the **Pro** plan. Free workspaces ship with a create limit of zero.

### Permissions

Quota operations require platform permissions. Each operation restates its permission inline.

| Default roles       | Permission       | Grants                           |
| ------------------- | ---------------- | -------------------------------- |
| All workspace roles | `gateway.view`   | List Quotas                      |
| `admin`, `operator` | `gateway.manage` | Create, update, or delete Quotas |

## Set a Quota

Create a USD spend cap for a workspace, agent, act-as subject, pool, model, or Gateway (`gateway`). Subject identity cannot change after create. Pass `--disabled` / `disabled` to create a Quota that is stored but not enforced until you enable it. Windows are `daily` (UTC midnight) or `monthly` (UTC month start, default `monthly`). Exhaustion behavior and event names are on the [Quotas](/reference/controls/quotas) reference.

<Callout icon="key">Requires `gateway.manage`.</Callout>

In the dashboard, open **Models → Cost quotas**, choose the subject and target, set the USD limit and window, then save. Model Quotas can cover a model globally or only within a selected pool, with an optional per-caller toggle.

<Tabs>
  <Tab title="CLI">
    ```bash title="Workspace monthly limit" theme={"system"}
    dome model quota set \
      --subject workspace \
      --limit 5000 \
      --window monthly \
      --name workspace-monthly
    ```

    ```bash title="Agent daily limit" theme={"system"}
    dome model quota set \
      --subject agent \
      --agent <agent-id> \
      --limit 25 \
      --window daily
    ```

    ```bash title="Pool monthly limit" theme={"system"}
    dome model quota set \
      --subject pool \
      --pool production \
      --limit 2500 \
      --window monthly
    ```

    ```bash title="Model budget within a pool" theme={"system"}
    dome model quota set \
      --subject model \
      --model claude-sonnet \
      --pool production \
      --limit 1000 \
      --window monthly
    ```

    | Flag           |   Required  | Description                                                            |
    | -------------- | :---------: | ---------------------------------------------------------------------- |
    | `--subject`    |     Yes     | `workspace`, `agent`, `act-as`, `pool`, `model`, or `gateway`          |
    | `--limit`      |     Yes     | Cap in US dollars                                                      |
    | `--window`     |      No     | `daily` or `monthly` (default `monthly`)                               |
    | `--name`       |      No     | Human-readable label                                                   |
    | `--agent`      | Conditional | Agent id when `--subject agent`                                        |
    | `--act-as`     | Conditional | Verified end-user OIDC `sub` when `--subject act-as`                   |
    | `--pool`       | Conditional | Pool name when `--subject pool`, or to scope a model Quota to one pool |
    | `--model`      | Conditional | Model connection name when `--subject model`                           |
    | `--gateway`    | Conditional | Gateway name or id when `--subject gateway`                            |
    | `--per-caller` |      No     | Model only: independent budget per agent and verified end user         |
    | `--disabled`   |      No     | Create without enforcement until enabled                               |

    <Callout icon="terminal">Reference: [`dome model quota set`](/cli/connect/models#quota-set)</Callout>
  </Tab>

  <Tab title="MCP">
    Tool: `dome_model_quota_set`

    ```json theme={"system"}
    {
      "subject": "model",
      "model": "claude-sonnet",
      "pool": "production",
      "limit_usd": 1000,
      "window": "monthly"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_model_quota_set`](/reference/mcp/models#dome_model_quota_set)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/CreateLLMQuota
    Content-Type: application/json

    {
      "workspace_id": "<workspace-uuid>",
      "subject_type": "model",
      "subject_id": "<model-connection-uuid>",
      "pool_id": "<pool-uuid>",
      "limit_micros": 1000000000,
      "window": "monthly",
      "name": "sonnet-in-production"
    }
    ```

    Limits are micro-USD on the API (`1000000000` is \$1,000.00). `scope` defaults to `total`. Set `per_caller` for per-caller model Quotas. For `act_as`, set `subject_key` to the OIDC `sub` instead of `subject_id`.

    <Callout icon="code">Reference: [`CreateLLMQuota`](/api/management/create-llm-quota)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Set a model Quota" theme={"system"}
    Create a monthly \$1000 Quota on model "claude-sonnet" within pool "production".
    ```
  </Tab>
</Tabs>

### Set an Act-As Quota

Create a Quota for one verified end-user subject. The Quota applies only when [Delegated agents](/connect/agents/delegated) verification has confirmed that subject on the call.

```bash theme={"system"}
dome model quota set \
  --subject act-as \
  --act-as user-123 \
  --limit 10 \
  --window daily
```

### Set a per-caller model Quota

Create a model Quota that tracks each agent and each verified end user independently instead of combining their spend.

```bash theme={"system"}
dome model quota set \
  --subject model \
  --model gpt-4o \
  --per-caller \
  --limit 5 \
  --window daily
```

## Set a Gateway Quota

Create a Quota that covers all LLM calls routed through a Gateway's model pools and direct model connections. This is the Gateway-first spelling of the same `gateway` subject available on `dome model quota set`.

<Callout icon="key">Requires `gateway.manage`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome gateway quota set prod-tools \
      --limit 500 \
      --window monthly \
      --name prod-monthly
    ```

    <Callout icon="terminal">Reference: [`dome gateway quota set`](/cli/connect/gateway#quota-set)</Callout>
  </Tab>

  <Tab title="MCP">
    Tool: `dome_gateway_quota_set`

    ```json theme={"system"}
    {
      "gateway": "prod-tools",
      "limit_usd": 500,
      "window": "monthly",
      "name": "prod-monthly"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_gateway_quota_set`](/reference/mcp/gateway#dome_gateway_quota_set)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/CreateLLMQuota
    Content-Type: application/json

    {
      "workspace_id": "<workspace-uuid>",
      "subject_type": "gateway",
      "subject_id": "<gateway-uuid>",
      "limit_micros": 500000000,
      "window": "monthly",
      "name": "prod-monthly"
    }
    ```

    <Callout icon="code">Reference: [`CreateLLMQuota`](/api/management/create-llm-quota)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Set a Gateway Quota" theme={"system"}
    Create a monthly \$500 Quota on Gateway "prod-tools" named "prod-monthly".
    ```
  </Tab>
</Tabs>

## Update a Quota

Update a Quota's name, USD limit, window, or enabled state. Subject identity cannot change. Create a new Quota to cover a different subject.

<Callout icon="key">Requires `gateway.manage`.</Callout>

Only the fields you pass change. Disable a Quota to pause enforcement without deleting its definition or history.

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome model quota update <quota-id> \
      --limit 7500 \
      --enabled true
    ```

    For Gateway Quotas, `dome gateway quota update` accepts the same mutable fields and refuses non-Gateway Quota ids.

    <Callout icon="terminal">Reference: [`dome model quota`](/cli/connect/models#quota-list)</Callout>
  </Tab>

  <Tab title="MCP">
    Tool: `dome_model_quota_update`

    ```json theme={"system"}
    {
      "quota_id": "<quota-id>",
      "limit_usd": 7500,
      "enabled": true
    }
    ```

    Use `dome_gateway_quota_update` for Gateway Quotas. It refuses ids that belong to other subjects.

    <Callout icon="cpu">Reference: [`dome_model_quota_update`](/reference/mcp/models#cost-quotas)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/UpdateLLMQuota
    Content-Type: application/json

    {
      "workspace_id": "<workspace-uuid>",
      "quota_id": "<quota-uuid>",
      "limit_micros": 7500000000,
      "enabled": true
    }
    ```

    Omitted optional fields keep their current values.

    <Callout icon="code">Reference: [`UpdateLLMQuota`](/api/management/update-llm-quota)</Callout>
  </Tab>
</Tabs>

## List Quotas

List Quotas in the workspace, including disabled ones. Listing returns each Quota's id, subject, USD limit, window, and enabled state.

<Callout icon="key">Requires `gateway.view`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome model quota list
    ```

    ```bash theme={"system"}
    dome gateway quota list [gateway]
    ```

    The Gateway list can filter to one gateway. It is a client-side filter over the workspace list.

    <Callout icon="terminal">Reference: [`dome model quota list`](/cli/connect/models#quota-list) · [`dome gateway quota list`](/cli/connect/gateway#quota-list)</Callout>
  </Tab>

  <Tab title="MCP">
    Tool: `dome_model_quota_list`

    ```json theme={"system"}
    {
      "name": "dome_model_quota_list",
      "arguments": {}
    }
    ```

    Tool: `dome_gateway_quota_list`

    ```json theme={"system"}
    {
      "gateway": "prod-tools"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_model_quota_list`](/reference/mcp/models#dome_model_quota_list) · [`dome_gateway_quota_list`](/reference/mcp/gateway#dome_gateway_quota_list)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/ListLLMQuotas
    Content-Type: application/json

    {
      "workspace_id": "<workspace-uuid>"
    }
    ```

    <Callout icon="code">Reference: [`ListLLMQuotas`](/api/management/list-llm-quotas)</Callout>
  </Tab>
</Tabs>

## Remove a Quota

Remove a Quota by id. Listing first is the usual way to obtain the id.

<Callout icon="key">Requires `gateway.manage`.</Callout>

<Warning>
  Remove deletes the Quota definition. Disable the Quota instead when you need to pause enforcement and keep the record.
</Warning>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome model quota rm <quota-id>
    ```

    ```bash theme={"system"}
    dome gateway quota rm <quota-id>
    ```

    The Gateway remove command refuses ids that belong to other subjects.

    <Callout icon="terminal">Reference: [`dome model quota rm`](/cli/connect/models#quota-remove) · [`dome gateway quota rm`](/cli/connect/gateway#quota-remove)</Callout>
  </Tab>

  <Tab title="MCP">
    Tool: `dome_model_quota_remove`

    ```json theme={"system"}
    {
      "quota_id": "<quota-id>"
    }
    ```

    Tool: `dome_gateway_quota_remove`

    ```json theme={"system"}
    {
      "quota_id": "<quota-id>"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_model_quota_remove`](/reference/mcp/models#dome_model_quota_remove) · [`dome_gateway_quota_remove`](/reference/mcp/gateway#dome_gateway_quota_remove)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/DeleteLLMQuota
    Content-Type: application/json

    {
      "workspace_id": "<workspace-uuid>",
      "quota_id": "<quota-uuid>"
    }
    ```

    <Callout icon="code">Reference: [`DeleteLLMQuota`](/api/management/delete-llm-quota)</Callout>
  </Tab>
</Tabs>

## Next steps

* [Quotas](/concepts/controls/quotas) concept for how spend caps work
* [Quotas](/reference/controls/quotas) reference for subjects, windows, and event names
* [Pools](/connect/resources/models/pools) for routing strategies and failover
* [Delegated agents](/connect/agents/delegated) so Act-As Quotas match live verified subjects
* [Models](/connect/resources/models) for the models and pools a Quota can target