Skip to main content
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. 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

List quotas

GET /coding/quotas Returns your organization’s quotas, each with its current usage.

Create a quota

POST /coding/quotas Cap a shared key at $1,000 a month:
Limit one engineer to 60 requests a minute on any key:
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}
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": "…"}}.

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:
For a request quota, the error type is rate_limit_error, and the response carries a Retry-After header: