Skip to content

Spending limits#

An autonomous agent can spend money in a loop. Limits are enforced at the LLM proxy, which is the one place every model call passes through.

Set a limit#

curl -fsS -X PUT \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  https://agents.example.com/v1/orgs/$ORG_ID/spending-limits \
  -d '{"actorType": "org", "period": "month", "limitCents": 500000}'

Set a $5,000 monthly spending limit for the whole acme org.

nexusctl spending-limit set --org acme \
  --actor-type org \
  --period month \
  --limit-cents 500000
Option Values
--actor-type org, user, agent, sandbox
--actor-id The user, agent, or sandbox id. Omit for an org-level limit.
--period day, week, month
--limit-cents Budget in cents. 500000 is $5,000. 0 blocks every request.

Limits are cents, not dollars — --limit-cents 5000 is fifty dollars, not five thousand.

Per sandbox, without the ids#

Cap the nightly-refactor sandbox at $50 a month.

nexusctl sandbox set-limit nightly-refactor \
  --project production --org acme \
  --period month --limit-cents 5000

This resolves the slug for you and is the same as a spending-limit set --actor-type sandbox --actor-id <id>.

What happens at the limit#

The proxy returns 429 and the sandbox keeps running.

That distinction matters. A capped agent loses model access, not its process, its disk, or its exposed port. It stops reasoning and keeps its state, so raising the limit resumes the work instead of restarting it.

An OpenAI realtime voice session behaves differently once it is open. A caller already over its limit is refused before the session opens, but a running session reports usage only as it goes, so the limit is re-checked per response and closes the session once passed, trailing actual spend by roughly 90 seconds.

Check status#

curl -fsS -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/orgs/$ORG_ID/spending-limits/status

How are we tracking against our spending limits this month? Flag
anything above 80% of its budget.

nexusctl spending-limit status --org acme

Each limit reports the budget, current spend, and what remains. Agents can read their own status — get_spending_limit_status is one of the few platform tools a sandbox identity is allowed to call, so a well-behaved agent can wind down before it is cut off.

Where the money went#

curl -fsS -G -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/orgs/$ORG_ID/usage-costs \
  -d breakdowns=model,provider,actorType

Break down last month's inference spend for the acme org by model,
provider, and actor type. What is driving the biggest line?
Parameter Purpose
projectId One project.
actorType, actorId One actor or class of actor.
provider, model One backend or model.
startTime, endTime ISO 8601 bounds.
breakdowns Comma-separated dimensions to group by.

A timeseries form is available at /v1/orgs/{orgId}/usage-costs/timeseries for charting spend over time.

Per-sandbox spend has a shortcut:

Which sandbox in production spent the most this week?

nexusctl sandbox spend nightly-refactor --project production --org acme

Layering limits#

Set them at more than one level. They apply independently, so the tightest one binds.

Scope Use it for
Org The number finance agreed to. Set this first.
User A per-engineer ceiling on interactive tool use.
Agent A budget for one agent identity across its sandboxes.
Sandbox A hard cap on one long-running or experimental agent.

A useful pattern for a new autonomous agent: a tight per-sandbox monthly cap while you learn its real cost, then relax it once the org-level trend is boring.

How spend is priced#

Most backends report token counts, which the platform prices against a bundled rate card.

OpenRouter is billed on what it charged. It states its cost on every response, on both wire formats, streamed or not, and that reported figure is what a limit is checked against. This closes a real gap: a model absent from the rate card prices as zero and counts toward no cap, and on a reseller adding models continuously the missing model is the newest one — which is exactly what an evaluator reaches for. openrouter/auto and openrouter/fusion, where a request naming no model routes, are among the ids this covers.

Where a request reports no cost, its tokens are still priced from the table, so every other backend behaves as it did. Pricing is per request rather than per period, so a period spanning an upgrade mixes reported and priced requests without billing either twice. The per-dimension breakdown describes only the priced remainder, which is why a fully reported period shows its total with zeros across the breakdown — the platform does not invent a split the provider never gave.

Only what the platform proxies#

Spending limits apply to managed inference, and they apply because the request travels through the platform's inference endpoint. Metering is a consequence of that routing, not of intercepting a sandbox's outbound TLS.

So a sandbox that dials a provider directly — through an allow entry for bedrock-runtime.*.amazonaws.com, bedrock-mantle.*.api.aws, an Azure Foundry host, or openrouter.ai — spends money that is neither metered nor gated. It writes no usage record and contributes nothing to any limit. A cap set on that sandbox reads like a cap on its spend and is not one.

The admin UI names this where it happens: a sandbox whose traffic is escaping metering carries a card listing the hosts it reached directly. The call count there is a floor rather than a total, because the platform is counting connections it did not read.

The remedy is a deny rule, not interception. Deny the provider host — which is the default posture — so the agent can reach the model only through the managed endpoint. openrouter.ai deserves the most attention: one key reaching roughly 60 vendors makes a direct dial there the cheapest way for an agent to spend money nothing meters.

If cost control matters, require managed inference in your org policy and keep provider domains denied. See Metering follows routing.