Set a session's budget

curl --request PUT \
  --url https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "maxCostUsd": "10.00"
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget"

payload = { "maxCostUsd": "10.00" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({maxCostUsd: '10.00'})
};

fetch('https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'maxCostUsd' => '10.00'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget"

	payload := strings.NewReader("{\n  \"maxCostUsd\": \"10.00\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"maxCostUsd\": \"10.00\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"maxCostUsd\": \"10.00\"\n}"

response = http.request(request)
puts response.read_body

{
  "continuesOnRaise": true,
  "maxCostUsd": "10.00",
  "agentCapUsd": "25.00",
  "spentUsd": "4.20"
}

{
  "code": "invalid_json",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unauthorized",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "not_found",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "conflict",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "payload_too_large",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unsupported_media_type",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "rate_limit_exceeded",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "internal_error",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "content_store_unconfigured",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

Sessions

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.

PUT

managed-agents

sessions

{sessionId}

budget

Set a session's budget

curl --request PUT \
  --url https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "maxCostUsd": "10.00"
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget"

payload = { "maxCostUsd": "10.00" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({maxCostUsd: '10.00'})
};

fetch('https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'maxCostUsd' => '10.00'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget"

	payload := strings.NewReader("{\n  \"maxCostUsd\": \"10.00\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"maxCostUsd\": \"10.00\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/budget")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"maxCostUsd\": \"10.00\"\n}"

response = http.request(request)
puts response.read_body

{
  "continuesOnRaise": true,
  "maxCostUsd": "10.00",
  "agentCapUsd": "25.00",
  "spentUsd": "4.20"
}

{
  "code": "invalid_json",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unauthorized",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "not_found",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "conflict",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "payload_too_large",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unsupported_media_type",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "rate_limit_exceeded",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "internal_error",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "content_store_unconfigured",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

Authorizations

Authorization

string

header

required

A Recursion API key, created in the console under API keys.

Headers

Idempotency-Key

string

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. 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.

Required string length: 1 - 256

Pattern: ^[!-~]+$

x-tenant-id

string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1

x-organization-id

string

Organization 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.

Minimum string length: 1

Path Parameters

sessionId

string<uuid>

required

Session id (UUID) as returned by managedAgentsStartSession or managedAgentsListSessions.

Body

application/json

The spend at which a session and its threads pause, 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, but requests already running finish and can pass it. Raising or removing it continues the session, except one bound to a Slack thread, which continues on its next reply there.

maxCostUsd

string

required

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.

Pattern: ^(0|[1-9][0-9]{0,5})(\.[0-9]{1,2})?$

Example:

"10.00"

Response

A session tree's budget and what it has spent toward it.

continuesOnRaise

boolean

required

read-only

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.

maxCostUsd

string

required

The budget in US dollars, with two decimals.

Pattern: ^(0|[1-9][0-9]{0,5})(\.[0-9]{1,2})?$

Example:

"10.00"

agentCapUsd

string

read-only

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.

Example:

"25.00"

spentUsd

string

read-only

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.

Example:

"4.20"

API reference

Endpoints

Set a session's budget

Authorizations

Headers

Path Parameters

Body

Response