# PATCH /v1/limits

> Set the day and month caps for the company and per user, and the alert thresholds, within what Vestra allows.

In [Account API](https://vestra.ai/developers/reference/api/account.md): Your company's account: who is calling, its keys, its caps, what it spent and the models it may use.

Send `Authorization: Bearer vk_test_...` on every call.

Set the day and month caps for the company and per user, and the alert thresholds, within what Vestra allows.

Your API key, scope `admin` or `all`. On the card: [`usage`](https://vestra.ai/developers/usage.md). Every call here is a checked sample.

## Request

Body:

- `org_daily_usd` (`number | null`): The company's cap per day (UTC), in US dollars with at most 2 decimals, up to `max_org_daily_usd`; null removes it. Limits: 0 to 1000000.
- `user_daily_usd` (`number | null`): The default cap per user per day (UTC), in US dollars, at most the company cap; null removes it. Limits: 0 to 1000000.
- `org_monthly_usd` (`number | null`): The company's cap per calendar month (UTC), in US dollars; null removes it. Limits: 0 to 1000000.
- `user_monthly_usd` (`number | null`): The default cap per user per calendar month (UTC), at most the company monthly cap; null removes it. Limits: 0 to 1000000.
- `alert_thresholds` (`integer[]`): Percents of a cap at which `usage.threshold_reached` fires, whole numbers from 1 to 100, at most four below 100. 100 always fires `usage.cap_reached`. Limits: at most 5 items. Example: `[50,80]`.

## Answers 200

- `object` (`"limits"`): Always `limits`.
- `mode` (`"live" | "test"`): The mode these limits belong to: the mode of the key in use.
- `org_daily_usd` (`number | null`): The company's spending cap per day (UTC), in US dollars, across all its users; null: none, up to the account's ceiling. Limits: 0 to 1000000.
- `user_daily_usd` (`number | null`): The default cap per user per day (UTC), in US dollars; a user's own `spend_cap_usd` wins. Null: none. Limits: 0 to 1000000.
- `max_org_daily_usd` (`number`): The highest the company's daily cap may be set, in US dollars. Ask Vestra to raise it. Limits: 0 to 1000000.
- `org_monthly_usd` (`number | null`): The company's cap per calendar month (UTC), in US dollars. Null (the default): none. Limits: 0 to 1000000.
- `user_monthly_usd` (`number | null`): The default cap per user per calendar month (UTC), in US dollars; a user's own `monthly_cap_usd` wins. Null (the default): none. Limits: 0 to 1000000.
- `alert_thresholds` (`integer[]`): Percents of a cap at which usage alerts fire, for the company and each user, per day and per month. Limits: at most 5 items.
- `rate_limits` (`object`): How fast you may call, fixed per account.
  - `requests_per_minute` (`integer`): Calls a key may make per minute before 429 `rate_limited`.
  - `concurrent_task_starts` (`integer`): How many computers your company may be waking at once with `warm`; past it, `warm` answers 429 `warm_limit`. Starting work is not limited by this number yet.

## Code

**TypeScript**

```ts
await vestra.usage.caps({ user_monthly_usd: 20 });
```

**Python**

```python
vestra.usage.caps(user_monthly_usd=20)
```

**CLI**

```bash
vestra usage caps --customer-monthly 20
```

**HTTP**

```bash
# See costs by user. This is what everything cost since the 1st, in billed US dollars.
curl "$VESTRA_BASE_URL/v1/usage?from=2026-10-01&group_by=user" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# See one user's spend.
curl "$VESTRA_BASE_URL/v1/usage?user_id=traveller-42" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# Get a conversation's receipt. It lists every charge, newest first.
curl "$VESTRA_BASE_URL/v1/usage/line-items?conversation_id=conv_8f2k" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# Set caps and alerts. This sets a monthly cap for each user, with alerts at 50% and 80% of it.
curl -X PATCH "$VESTRA_BASE_URL/v1/limits" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_monthly_usd": 20, "alert_thresholds": [50, 80] }'
```

**MCP**

```json
{
  "method": "tools/call",
  "params": {
    "name": "usage",
    "arguments": { "from": "2026-10-01", "group_by": "user" }
  }
}
```