GET /agents/runs/{id}, error.type = "AgentLoopBudgetExhausted"
When this error occurs
Some runs carry a budget: a token allowance for the whole run, written by the platform when the run is created. Runs started through the Conversations API do not have one — they are bounded bymax_iterations alone, and cannot produce this error. Runs the platform starts on your behalf,
such as a workflow’s RunConversation task, do.
The budget covers every call to the model made by the run and by any run it starts, added up. It
is not the same as max_tokens, which caps a single call, nor max_iterations, which caps how
many rounds one run may take — a run can think and call tools many times without touching its
budget.
The check happens after an iteration finishes, not before it starts, because how many tokens an
iteration will use is not known until it has run. A run can therefore finish slightly over its
allowance — by at most one iteration’s worth. The usage on the terminal run row records what
was actually spent.
A run that runs out of rounds rather than tokens reports
Max Iterations Exceeded
instead.
How to fix
- The work genuinely needs more tokens — raise the budget for the surface that created the
run. For a workflow’s
RunConversationtask, that is worker configuration, not something the workflow spec sets. - The agent is spending tokens without progressing — read the conversation transcript. Long tool results fed back verbatim are the usual cause; so is a prompt that leaves the model unsure when it is finished. Narrowing the tool catalog or sharpening the system prompt costs fewer tokens than raising the ceiling.