LLM quotas
An agent can call an LLM far more often than a single query does: once for
its own reasoning steps, again for any tool that overrides the LLM it
runs on, again during compaction and memory extraction, and again for any
enrichment tool that itself calls an LLM. llm_quota puts a ceiling on that
total spend so one agent cannot exhaust a shared LLM's capacity or run up
an unbounded bill.
What a quota limits
llm_quota accepts seven optional integer fields, each enforced
independently of the others.
| Field | Counts | Window |
|---|---|---|
requests_per_second | LLM requests the agent makes (1-10000). | Per second |
input_tokens_per_minute | Input (prompt) tokens, as reported by the provider, including cached prompt tokens. | Per minute |
output_tokens_per_minute | Output tokens (completion plus reasoning). | Per minute |
input_tokens_per_day | Input tokens. | Per UTC calendar day |
output_tokens_per_day | Output tokens. | Per UTC calendar day |
input_tokens_per_month | Input tokens. | Per UTC calendar month |
output_tokens_per_month | Output tokens. | Per UTC calendar month |
An omitted field applies no limit for that field. Every token field must be at least 1. Day and month windows reset on UTC boundaries, not the agent's local timezone.
Output tokens are defined the same way wherever a session reports them.
session_context_usage.output_tokens.count, on the context_consumed event
and on the agent session, includes reasoning tokens. Its reasoning_tokens
is a subset of count, not an addition to it.
This mirrors the per-LLM request and token limits you can set on an LLM configuration itself, but the two are independent and serve different purposes: an LLM's quota bounds that LLM's total capacity across every caller, while an agent's quota bounds what one agent spends regardless of which LLMs it calls.
What counts against the quota
An agent's quota is charged for every LLM call the agent makes, across every LLM involved in running it:
- The agent's own configured LLM, for its reasoning steps.
- A tool configuration's LLM override, when a tool runs on a different LLM than the agent's.
- Compaction, when the agent summarizes earlier events to free up context.
- Memory extraction, when the agent extracts learned facts at the end of a session.
- Session enrichment, when an enrichment-only tool configuration itself calls an LLM.
A sub-agent invoked through sub-agents charges
its own llm_quota, not its parent's. Each agent in the chain is
responsible for its own spend, whatever agent is calling it.
How enforcement works
The platform checks a quota before each call and charges the call's reported usage after it, so a window may exceed its limit by at most one in-flight call per concurrent request, the same imprecision accepted on per-LLM quotas.
Once a limit is reached, the agent's next LLM call is refused, and how you
see that depends on how you sent the input event. A non-streamed input
request that is refused answers HTTP 429 with a Retry-After header giving the
seconds until the window resets. A streamed request ends with an error
event whose message names the exhausted quota and the same number of
seconds.
Set a quota
llm_quota is a field on the agent, alongside model and
tool_configurations. Set it when you create the agent, or add it later
with PUT /v2/agents/{agent_key} (replace) or PATCH /v2/agents/{agent_key}
(update).
CREATE AN AGENT WITH A TOKEN BUDGET
Code example with json syntax.1
Update a quota
PATCH /v2/agents/{agent_key} treats llm_quota as a single object, not a
set of independently patchable fields: sending it replaces the whole
quota, so include every field you want to keep. This differs from the
per-field PATCH semantics on an LLM's token fields, where omitting a field
keeps its current limit.
REPLACE THE QUOTA WITH A PATCH
Code example with json syntax.1
Set llm_quota to null on a PATCH to remove every limit. Omit the field
entirely to leave the current quota unchanged.
Related
- Bring your own LLM: Limit requests and tokens — the equivalent per-LLM quota.
- Sub-agents — how a sub-agent's own quota applies to its calls.
- Compaction and Memory — two of the paths that charge against the quota.