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

# Create and audit a budget

> Set a workspace spending limit and inspect recorded spend with the CLI.

A budget action limits the recorded USD cost of matching requests within a UTC calendar day or month. The rule's target and request match select which usage counts. `shared` combines matching usage into one allowance; `per_key` gives each inference key its own allowance.

This guide creates a shared monthly budget of \$20, then checks its spend. The same steps work for daily budgets by changing `period` to `day`.

## Create a budget policy

Save this as `budget-policy.json`:

```json theme={null}
{
  "name": "Production monthly budget",
  "enabled": true,
  "definition": {
    "target": {"kind": "workspace"},
    "rules": [
      {
        "match": {"kind": "all_requests"},
        "action": {
          "kind": "budget",
          "amount_usd": "20.00",
          "period": "month",
          "aggregation": "shared"
        }
      }
    ]
  }
}
```

Create the policy in your active organization and workspace context:

```bash theme={null}
airmux policies create budget-policy.json --workspace production -f json
```

The CLI prints a JSON array. Copy the returned `id` for the status command:

```json theme={null}
[
  {
    "id": "01990aa3-4b4c-7000-8000-000000000001",
    "org_id": "01990aa3-4b4c-7000-8000-000000000002",
    "workspace_id": "01990aa3-4b4c-7000-8000-000000000003",
    "name": "Production monthly budget",
    "enabled": true,
      "definition": {
      "target": {"kind": "workspace"},
      "rules": [
        {
          "match": {"kind": "all_requests"},
          "action": {"kind": "budget", "amount_usd": "20.00", "period": "month", "aggregation": "shared"}
        }
      ]
    },
    "created_at": "2026-09-23T18:00:00Z",
    "updated_at": "2026-09-23T18:00:00Z"
  }
]
```

## Check spending

The status output reports the UTC window, spend, remaining allowance, exhaustion, and calculation time. A monthly window starts on the first day of the month and ends on the first day of the next month. Shared budgets return one `shared` bucket.

```bash theme={null}
airmux policies status "$POLICY_ID" --workspace production -f json
```

The CLI prints a JSON array, one row per budget rule:

```json theme={null}
[
  {
    "rule_index": 0,
    "aggregation": "shared",
    "amount_usd": "20.00",
    "period": "month",
    "window_start": "2026-09-01T00:00:00Z",
    "window_end": "2026-10-01T00:00:00Z",
    "buckets": [
      {
        "bucket": {"kind": "shared"},
        "spent_usd": "12.40",
        "remaining_usd": "7.60",
        "exhausted": false
      }
    ],
    "next_bucket": null,
    "computed_at": "2026-09-23T18:30:00Z"
  }
]
```

Example amounts and timestamps are illustrative. `computed_at` marks when status was calculated from recorded usage. Usage from earlier in the current period also counts, including usage recorded before the policy was created.

## Audit per-key budgets

For separate allowances per inference key, set `aggregation` to `per_key` in the budget action before creating the policy. Each returned bucket identifies a key and reports its spend and remaining allowance:

```json theme={null}
{
  "bucket": {"kind": "key", "key_id": "key-id-1"},
  "spent_usd": "8.25",
  "remaining_usd": "11.75",
  "exhausted": false
}
```

Set `KEY_ID` to a key ID from a bucket. If it has no matching recorded usage in the current window, the query reports zero:

```bash theme={null}
airmux policies status "$POLICY_ID" -w production --rule-index 0 --bucket-id "$KEY_ID" -f json
```

To inspect all key buckets, request a page. When more buckets remain, `next_bucket` has the form `{"kind":"key","key_id":"key-id-100"}`. Pass its `key_id` as `AFTER_BUCKET` for the next page:

```bash theme={null}
airmux policies status "$POLICY_ID" -w production --rule-index 0 --limit 100 -f json
airmux policies status "$POLICY_ID" -w production --rule-index 0 --after-bucket "$AFTER_BUCKET" --limit 100 -f json
```

Rule indices start at zero and follow the order in the policy's `definition.rules` array. The status command requires a CLI profile with `policies.read` and `usage.read` permissions in the workspace. A request blocked by an exhausted budget receives `429 budget_exhausted` with a `Retry-After` header.