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

# Quotas API

> Set spend and request limits on a ValarCode key, and request limits on an engineer, and read usage against each limit

Private Preview

The Quotas API lets your organization limit its own ValarCode traffic without contacting Valar. You can set:

* **Key quotas**: limits on every request sent with one coding key, whoever sends it. Use these when several engineers share a key.
* **User quotas**: request-rate limits on one engineer, across every coding key in your organization. The engineer is identified by the client id you see on the **Users** page and in usage.

To cap one engineer's spend, use the monthly and daily quota on the **Users** page. User quotas don't limit spend.

## Quota types

Each quota sets one limit over one period.

| Subject | Metric | Periods | Limit |
| - | - | - | - |
| `key` | `spend_usd` | `day`, `month` | US dollars, in whole cents |
| `key` | `requests` | `minute`, `hour` | A whole number of requests |
| `user` | `requests` | `minute`, `hour` | A whole number of requests |

A key or user can have one quota for each metric and period. For example, a key can have a $50 daily limit, a $1,000 monthly limit, and a limit of 120 requests per minute.

## Authentication

The endpoints are served under `https://app.valarhq.ai/api` and use your Valar dashboard sign-in.

* Any role in your organization can list and read quotas.
* Creating, changing, and deleting quotas requires the **member** or **admin** role. Other roles get `403`.

## The quota object

```json theme={"system"}
{
  "id": "cq_3f9a1c7d2b8e4f60",
  "subject": "key",
  "key_id": "key_8f2c1a7d0b3e4f59",
  "engineer_id": null,
  "metric": "spend_usd",
  "period": "month",
  "limit": 1000,
  "usage": {
    "used": 123.45,
    "remaining": 876.55,
    "exceeded": false,
    "resets_at": "2026-11-01T00:00:00Z"
  },
  "created_at": "2026-10-26T16:00:00Z",
  "updated_at": "2026-10-26T16:00:00Z"
}
```

| Field | Type | Description |
| - | - | - |
| `id` | string | The quota's id, starting with `cq_`. |
| `subject` | string | `key` or `user`. |
| `key_id` | string or null | The coding key, for a `key` quota. `null` for a `user` quota. |
| `engineer_id` | string or null | The engineer's client id, for a `user` quota. `null` for a `key` quota. |
| `metric` | string | `spend_usd` or `requests`. |
| `period` | string | `day` or `month` for `spend_usd`. `minute` or `hour` for `requests`. |
| `limit` | number | US dollars for `spend_usd`, requests for `requests`. |
| `usage` | object or null | Where the quota stands now. `null` if Valar couldn't read the usage at that moment; the quota is still enforced. |
| `usage.used` | number | Spend so far in the period, or requests used from the allowance. |
| `usage.remaining` | number | What is left before the limit. Never below 0. |
| `usage.exceeded` | boolean | `true` once the limit is reached. New requests are refused until the period resets. |
| `usage.resets_at` | string | When a spend period ends, or when a request allowance is full again. UTC, RFC 3339. |
| `created_at`, `updated_at` | string | UTC, RFC 3339. |

## List quotas

`GET /coding/quotas`

Returns your organization's quotas, each with its current usage.

| Query parameter | Description |
| - | - |
| `subject` | Only `key` or only `user` quotas. |
| `key_id` | Only quotas on this coding key. |
| `engineer_id` | Only quotas on this engineer. |

```json theme={"system"}
{
  "quotas": [
    { "id": "cq_3f9a1c7d2b8e4f60", "subject": "key", "key_id": "key_8f2c1a7d0b3e4f59", "engineer_id": null, "metric": "spend_usd", "period": "month", "limit": 1000, "usage": { "used": 123.45, "remaining": 876.55, "exceeded": false, "resets_at": "2026-11-01T00:00:00Z" }, "created_at": "2026-10-26T16:00:00Z", "updated_at": "2026-10-26T16:00:00Z" }
  ]
}
```

## Create a quota

`POST /coding/quotas`

| Body field | Required | Description |
| - | - | - |
| `subject` | Yes | `key` or `user`. |
| `key_id` | For `key` | A coding key in your organization that hasn't been revoked. |
| `engineer_id` | For `user` | The engineer's client id exactly as it appears in usage. Aliases aren't merged. |
| `metric` | Yes | `spend_usd` (keys only) or `requests`. |
| `period` | Yes | See [quota types](#quota-types). |
| `limit` | Yes | A positive number: whole cents for `spend_usd`, a whole number for `requests`. |

Cap a shared key at \$1,000 a month:

```json theme={"system"}
{
  "subject": "key",
  "key_id": "key_8f2c1a7d0b3e4f59",
  "metric": "spend_usd",
  "period": "month",
  "limit": 1000
}
```

Limit one engineer to 60 requests a minute on any key:

```json theme={"system"}
{
  "subject": "user",
  "engineer_id": "alice@example.com",
  "metric": "requests",
  "period": "minute",
  "limit": 60
}
```

Returns `201` with the new quota. If the key or user already has a quota for that metric and period, returns `409`; change that quota's limit instead.

## Get a quota

`GET /coding/quotas/{id}`

Returns one quota with its current usage.

## Change a quota's limit

`PATCH /coding/quotas/{id}`

```json theme={"system"}
{ "limit": 1500 }
```

Only `limit` can change. You can send the whole quota back with a new `limit`. If any other field differs from the stored quota, the request returns `400`: delete the quota and create a new one instead.

Returns `200` with the updated quota.

## Delete a quota

`DELETE /coding/quotas/{id}`

Returns `200` with `{"id": "cq_…", "deleted": true}`. The limit stops applying within about 30 seconds.

## Errors

The API returns errors as `{"error": {"type": "…", "message": "…"}}`.

| Status | When |
| - | - |
| `400` | The body or a parameter is invalid: an unknown subject, metric, or period; a spend quota on a user; a limit that isn't positive, isn't in whole cents, or isn't a whole number of requests; a `key_id` that isn't a live coding key in your organization. |
| `403` | Your role can't create, change, or delete quotas. |
| `404` | No quota with that id in your organization. |
| `409` | The key or user already has a quota for that metric and period. |

## How quotas are enforced

A new or changed quota applies to coding requests within about 30 seconds.

A request must pass every limit that applies to it, so the strictest one wins. Quotas only add limits. They never raise your organization's spend limits, the limits Valar sets for your organization, your prepaid credit balance, or the engineer quotas on the **Users** page.

### Periods

* **`day`**: the current UTC day. It resets at 00:00 UTC.
* **`month`**: the current UTC calendar month. It resets on the 1st at 00:00 UTC.
* **`minute`** and **`hour`**: a rolling allowance. The full limit is available at once. After that, capacity refills steadily over the period. A request that another limit refuses doesn't use the allowance.

Spend is the amount Valar bills for the key's traffic, the same figure as on your invoice. It's checked before each request starts, so a request already running when spend reaches the limit finishes, and the next request is refused.

### Your own provider key (BYOK)

Traffic served on your own provider key is billed by the provider, so spend quotas don't apply to it. Request quotas still apply.

### What engineers see

When a quota is reached, the request fails with HTTP `429` before it reaches a model.

For a spend quota, the error type is `billing_error`, and the message names the limit and when it resets:

```json theme={"system"}
{
  "error": {
    "type": "billing_error",
    "message": "ValarCode quota exceeded: this API key's monthly spend limit of $1000.00 is reached. It resets at 2026-11-01T00:00:00Z."
  }
}
```

For a request quota, the error type is `rate_limit_error`, and the response carries a `Retry-After` header:

```json theme={"system"}
{
  "error": {
    "type": "rate_limit_error",
    "message": "ValarCode quota exceeded: this user's request rate limit is reached."
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.