Spend limits and the ledger

Every request runs on your own provider key, so what you need to control is how much of your provider bill a key, a client, an agent or a policy can run up. Four kinds of ceiling do that, each checked before a request reaches a provider, and every request leaves a priced record you can audit afterwards.

Four kinds of ceiling

• Per key: one application or environment. PATCH /v1/keys/:hash with limit, limit_reset and limit_mode, or the Keys page.
• Per guardrail: a budget on a policy, for every key or member it is assigned to (limit_usd, reset_interval).
• Per workspace: one client, across all of its keys, one budget per interval.
• Per agent: an agent named in X-Autonomous-Relay-Agent, across every key it uses, without touching other agents on the same key.

Windows are daily, weekly, monthly or lifetime. Each level is checked on its own and never added to another: a $100 workspace budget and a $50 key ceiling do not make $150, and the first one reached refuses the request. Key ceilings, agent budgets and the first workspace’s budgets work on every plan; guardrail budgets, usage-alert channels and the CSV export come with the Team plan.

What a ceiling counts

What each request costs at the provider’s list price — the spend your provider bills you — counted in the ceiling’s current window. A $50 monthly ceiling stops the key at $50 of it. This is the default for every kind of ceiling; set include_byok_in_limit (or include_byok_in_budgets, include_byok) to false to count only spend on platform capacity, of which there is none today. A request that produced nothing is not counted.

Hard or soft

A hard ceiling, the default, refuses the request with 403 budget_exceeded before any provider is contacted, and the refusal is recorded, so Activity shows what was stopped and why. A soft ceiling serves the request and adds an x-autonomous-relay-limit-warning header carrying the same sentence: for a limit you want to hear about rather than enforce.

Why parallel requests cannot overshoot

Before dispatch, each request reserves its largest possible cost, at list price, against every ceiling that applies; at settlement the reservation becomes the real cost and the rest is released. A burst of requests is therefore refused at the ceiling, not after it: twenty requests each within the limit cannot together spend past it. GET /v1/keys reports each key’s usage and limit_remaining with the reservations of requests still in flight included, exactly as the ceiling is enforced. Failover does not get around a ceiling either: the check happens once, before the first attempt.

A worked example

A support bot on one key: at most $50 a month, its agent capped at $10 a day, and a Slack message at 80% and 100%.

# The key: a hard $50 monthly ceiling.
curl -X PATCH https://autonomousrelay.com/v1/keys/$KEY_HASH \
  -H "Authorization: Bearer $AUTONOMOUSRELAY_MANAGEMENT_KEY" \
  -H 'content-type: application/json' \
  -d '{"limit": 50, "limit_reset": "monthly", "limit_mode": "hard"}'

# The agent: $10 a day, wherever its requests come from.
curl -X PUT https://autonomousrelay.com/v1/agents/support-bot/budgets/daily \
  -H "Authorization: Bearer $AUTONOMOUSRELAY_MANAGEMENT_KEY" \
  -H 'content-type: application/json' \
  -d '{"limit_usd": 10}'

Then, on Team, add a Slack, webhook or email channel under Alerts: a key with a ceiling is announced as it crosses 50%, 80% and 100%, or the thresholds you choose, once per threshold per window.

Runaway spend, without a ceiling

A key or an agent whose last 15 minutes cost at least three times its usual (and at least $5) is flagged on your alert channels as spend.runaway. Set runaway_action to pause and the key is also paused until you resume it. See Limits & credits for the thresholds.

Auditing spend afterwards

Every request is metered into priced lines — prompt, completion, reasoning, cache and the like — each carrying the unit price it was billed at, so an old charge recomputes to the same figure after prices change. GET /v1/generation?id=:id shows one request’s lines and the endpoint that served it; GET /v1/activity/upstream shows every attempt; and GET /v1/activity/export.csv gives a month of requests, for the organisation or one client, with list_price_usd, the figure ceilings measure. See Billing & the ledger.