Set a session's budget
Sets a root session tree’s budget and returns it. The budget must be more than the tree has already spent and no more than the agent’s multiagent.limits.max_tree_cost_usd; a budget that reached that cap cannot be raised, and a thread or grader returns 400 naming its root. Work paused at the old budget continues as soon as the budget is saved: the service sends the root a short message saying the budget changed, through the same admission as any message, so a tenant that is out of credit returns 403 session_start_not_admitted and the work stays paused under its new budget; repeating the request once the refusal is resolved continues it. Once the message is delivered, repeating the request sends nothing, so a retry never starts another turn. A finished tree is not restarted, and a session bound to a Slack thread (continuesOnRaise false) continues on its next reply there. Returns 400 where session budgets are not available to the caller.
Authorizations
A Recursion API key, created in the console under API keys.
Headers
Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry.
1 - 256^[!-~]+$Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.
1Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.
1Path Parameters
Session id (UUID) as returned by managedAgentsStartSession or managedAgentsListSessions.
Body
The most a session and its threads may spend, in US dollars at the billed price, counting model requests, tools and sandbox compute. On Recursion, linked outcome grading sessions count toward the writer's budget when they share that budget. Reaching it pauses the session with stop_reason budget_reached before its next paid request; raising or removing the budget continues it.
The budget in US dollars, as a decimal string with at most two decimals, such as "10" or "12.50". Between 0.01 and 100000.
^(0|[1-9][0-9]{0,5})(\.[0-9]{1,2})?$"10.00"
Response
A session tree's budget and what it has spent toward it.
A session tree's budget and what it has spent toward it.
Whether raising or removing the budget of a session paused at it continues the session right away. False for a session bound to a Slack thread, which continues on its next reply there.
The budget in US dollars, with two decimals.
^(0|[1-9][0-9]{0,5})(\.[0-9]{1,2})?$"10.00"
The agent's multiagent.limits.max_tree_cost_usd, in US dollars with two decimals: the most this budget can be set to. A session whose budget reached it stays paused; start a new session, or raise the agent's cap for sessions started after.
"25.00"
What the session tree has spent, plus any linked outcome grading sessions charged to the same budget on Recursion, in US dollars with two decimals, at the billed price the budget is enforced at (models, tools and sandbox compute). Present on a full read of the root; absent when the spend could not be read. A session that paused at its budget can read a little past it: the request that crossed it completes.
"4.20"