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.

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.

Only what the platform proxies#

Spending limits apply to managed inference. An agent holding its own provider key and calling the provider through an allowed domain is not metered — the platform is forwarding bytes, not pricing a model request.

If cost control matters, require managed inference in your org policy and do not allow provider domains directly.