Budgets & Limits

Budgets & Limits is where you decide how much the gateway is allowed to spend, and what it does when it gets there. Before a request reaches the provider, CoreValue checks it against every budget that covers it.

Before you start

How budgets work

A request can be covered by up to five budgets at once — for example, the organisation's, its team's, and its key's own cap. Every one that applies must have room left; the first one that is full decides what happens:

True of every budget:

• Every budget on this page is monthly and resets on the 1st of the calendar month (UTC). A budget set mid-month counts the spend already made that month. Daily and yearly ceilings, in preview, are on Daily and yearly ceilings; there are no weekly budgets.
• Spend is what the provider charged, priced by CoreValue at the model's list price — whether the request used your own provider key or credits.
• Changes take effect within about a minute. The gateway caches budget settings for up to 60 seconds.
• If CoreValue cannot read a budget (for example during an outage of its own database), the request is served rather than refused. Budgets never take your traffic down.

What happens at the budget

Each budget has an action. You choose it for each budget, or leave it to follow the organisation's.

Set the organisation budget

Downgrade mappings

When Downgrade model is selected, a Model Downgrade Mappings section appears under the form. Each mapping says "when the budget is exceeded, rewrite requests for this model to that one".

1. Enter the Source Model exactly as your application sends it, for example gpt-4o or anthropic/claude-sonnet-4-5-20250929.
2. Enter the Target Model to use instead, for example gpt-4o-mini.
3. Click Add Mapping.

A request for a model with no mapping is refused, so add a mapping for every model you use.

Set a team budget

Teams group keys, and a team budget caps what all of the team's keys spend together.

Set a member budget

A member budget caps the spend on every key that member owns. Keys with no owner are shared service keys: they count towards no member, so cap them on the Keys tab instead.

1. Go to Budgets & Limits → Members.
2. Click Set budget (or Edit budget) on the member's row.
3. Fill in the dialog and click Save.

To remove a budget, open the dialog and click Remove budget.

Set a customer budget

If your product serves your own customers, send their ID on each request with the Cova-Customer-Id header. The Customers tab then shows spend per customer, and lets you budget each one.

curl https://gateway.corevalue.dev/v1/chat/completions \
  -H "Authorization: Bearer $COVA_API_KEY" \
  -H "Cova-Customer-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}'

1. Go to Budgets & Limits → Customers. Customers with a budget or a price are listed; every customer ID seen this month can be picked when you add one.
2. Click Add limit, choose the Customer, and click Continue. (Or Edit budget on a row that has one.)
3. Enter the Monthly budget (USD) and choose At the budget, then click Save.

Customer IDs are matched without regard to case: Acme-Corp and acme-corp are the same customer.

Price and Default price on this tab record what you charge each customer, so the tab can show revenue and margin next to cost. They are available on the Growth and Enterprise plans.

Cap a virtual key

A virtual key is a CoreValue key that can carry its own limits: a monthly spending cap, and limits on how many requests it can make. Give a service its own virtual key when you want to cap that service on its own.

A key with no cost cap of its own uses the organisation's Default cap per virtual key, if you set one on the Organization tab.

API keys (listed under the virtual keys) have no cap of their own. They are limited by their team's budget and the organisation budget.

Get told before the budget runs out

Alerts are configured on Notifications → Budget alerts, not on this page.

Click Save Recipients. Recipients are also emailed when a budget refuses, at most once an hour per budget.

See what your budgets did

Budgets & Limits → Actions shows what budgets, key caps, daily and yearly ceilings and velocity limits did to requests. Policy refusals (PII, key scopes, rate limits) are not included.

Pick a range (last 24 hours, 7 days, 30 days, this budget month, or custom dates up to 92 days) and, optionally, filter by scope, outcome and window. The tab shows:

What the outcomes mean:

• Would refuse (preview): a ceiling that is still in preview was over its limit. The request was served. It is never counted as Refused.
• Over an alert ceiling: the request went over a ceiling whose action is alert, and was served. It does not mean an alert was delivered.
• Not evaluated: the budget could not be checked and your organisation fails closed, so the request was refused.

Member and customer budgets act only by refusing. Requests before 17 September 2026 carry no verdict and are not counted.

The counts and the event log count different things: the counts are requests, and the log has one row per layer that acted, so a request can appear in it more than once. The log records enforced actions only; filters it cannot apply (model, would refuse, not evaluated, velocity) are shown greyed out above it.

Breach History at the bottom of the Organization tab now links to this tab. The Teams, Members, Customers and Keys tabs still show a Last acted date per row.

Who can see it. The counts and the chart need the Read traffic permission; the event log needs Read reports. A member without Read reports sees the counts and a locked event log.

Rate limits

The Rate limits tab limits how many requests (or how many cents) the gateway accepts in a rolling window, independent of budgets.

1. Go to Budgets & Limits → Rate limits → Rate Limit Rules, and click Create Rule.

2. Fill in the rule:

   Field	What it does	Default
   Rule Name	A name for the rule.	—
   Quota	How many units are allowed per window.	—
   Unit	Requests or Cents.	Requests
   Time Window (sec)	The rolling window, in seconds — 3600 for one hour.	—
   Apply To	All Requests (Global), Each User ID (per Cova-User-Id), or Custom Property (per value of a Cova-Property-* header you name).	All Requests (Global)

3. Click Create Rule.

When several rules match a request, property rules apply first, then user rules, then global rules. Rate Limited Requests lists the requests that were refused.

What your application sees

A request stopped by a budget or cap gets HTTP 429, in the same error format as the provider you called, so your existing error handling keeps working. For an OpenAI-format request:

HTTP/1.1 429 Too Many Requests

{
  "error": {
    "message": "Monthly budget of $125.00 exceeded. Current spend: $125.04. Manage your budget at https://app.corevalue.dev/settings/budget",
    "type": "rate_limit_error",
    "code": null
  }
}

HTTP/1.1 429 Too Many Requests

{
  "error": {
    "message": "Proxy key spend limit exceeded",
    "type": "rate_limit_error"
  }
}

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error"
  }
}

Anthropic-format requests get {"type": "error", "error": {"type": "rate_limit_error", ...}}, and Gemini-format requests get "status": "RESOURCE_EXHAUSTED".

Troubleshooting

Related

• Quickstart — send your first request
• Block models — limit a key to certain models or providers
• Headers reference — Cova-Customer-Id, Cova-User-Id and the rest