Velocity limits

A monthly budget tells you a key overspent after the month is gone. A velocity limit watches a short, rolling window instead, for example "no more than $25 in any 5 minutes", so a script stuck in a loop is caught while it is still cheap.

What a limit is

A limit applies to one proxy key, or to one agent, over one window:

• Window: a whole number of minutes, from 1 minute to 1 day (for example 5 minutes, 1 hour or 1 day).
• Limit: an amount in US dollars. You choose it; nothing is filled in for you.
• Action: what happens when spend in the window goes above the limit.

You can set more than one window on the same key, for example 5 minutes and 1 hour. A request that would take spend in a window past its limit is the one that is stopped; a window that reaches exactly the limit is still served. An organization can have up to 50 velocity limits.

Limits on an agent

An agent limit counts every request made with any key bound to the agent, as one window. An agent that calls with three keys has one ceiling, where three key limits would give it three. Register the agent under Gateway › Agents (one with no endpoint is enough) and bind its keys there.

• API keys count too. A key limit applies to proxy keys only; an agent limit counts the agent's API keys and proxy keys alike.
• The agent is read from the key, never from a header, so a caller cannot choose to escape it. A request made with a key bound to no agent is not counted by any agent limit.
• Binding changes take up to a minute to reach the gateway.
• MCP tool calls are not priced yet, so they add nothing to an agent's window.

A refused request is recorded with the rule velocity:agent:<agent id>:<window>s, where the agent id is the agent's internal id, not its name.

Session caps

A session cap limits what each session on a proxy key may spend in total, so one run that goes wrong is refused while the key's other sessions carry on. A session is the requests that carry the same Cova-Session-Id header on the same key; a request without the header is not counted by any session cap.

• Limit: an amount in US dollars for the whole session. A session cap always blocks: the request that would take the session past it is refused.
• Idle timeout: a session that sends no request for this long is forgotten, and the same id starts again from zero. One hour unless you set another, from 5 minutes to 1 day.
• One per key. A key has at most one session cap.

A refused request gets HTTP 429 with no Retry-After (waiting does not clear a session cap), and is recorded with the rule session_cap:key. Requests served on your own provider key are never refused by a session cap. Session caps send no alerts; refusals show in the Governance panel and on the request.

What is counted

Spend is counted in dollars, the same way budgets count it: CoreValue reserves the worst-case cost of a request before it runs, then corrects to the actual cost when it finishes. Spend on your own provider keys counts toward the window, because a runaway on your own key costs you just the same. A limit on a key that uses your own provider key alerts but never blocks.

The window slides: it always covers the most recent stretch of time, so a limit does not reset at the top of the hour. The counted span can run slightly longer than the window you set (by at most about a twelfth of it), never shorter.

Set a limit

1. Open Budgets & Limits → Velocity.
2. Press Add limit.
3. Choose whether it applies to a key, an agent or each session on a key. For a key or an agent, choose it, the window, the limit in dollars and the action. For a session cap, choose the key, the limit and, if you want other than one hour, the idle timeout.
4. Save.

You can switch a limit off without deleting it, edit its amount or action, or delete it. What it applies to and the window cannot be changed on an existing limit; add a new one instead. Deleting an agent deletes its limits. Anyone in the organization can see the limits; adding, editing, switching and deleting need permission to manage spend controls.

When a request is blocked

With Block requests and enforcement on, a refused request gets HTTP 429 in your provider's own error format, with a Retry-After header that says how many seconds until enough spend leaves the window. The limit clears by itself as the window slides; nobody needs to reset it. The request is recorded with the rule velocity:key:<window>s, for example velocity:key:300s for a 5-minute window.

If CoreValue cannot check

Velocity limits are a backstop, so they fail open: if the limits cannot be read or the counter is unavailable, the request is served and CoreValue logs why. The one exception is an organization whose budget fail mode is set to fail closed; a blocking limit that could not be checked refuses the request with 503.

Alerts

While limits are in preview, they are not checked, so no breach is recorded and no alert is sent. Once enforcement is on, an alert names the key (or the agent), the window, the limit and the spend, and says whether requests are being refused. It is sent to your budget alert recipients by email. Webhook delivery of velocity alerts is not available yet; webhooks carry request logs only. A key that keeps breaching sends one alert every five minutes, not one per request.

What is not included yet

• Velocity limits per member, team, customer or organization. Today a velocity limit applies to a proxy key or an agent, and a session cap to each session on a proxy key.