Define what done looks like for a session

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/outcomes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "Export the product catalog to /out/catalog.csv",
  "rubric": "- /out/catalog.csv exists\n- The CSV has a header row with sku, name, and price columns\n- Every price value is a number"
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/outcomes"

payload = {
    "description": "Export the product catalog to /out/catalog.csv",
    "rubric": "- /out/catalog.csv exists
- The CSV has a header row with sku, name, and price columns
- Every price value is a number"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    description: 'Export the product catalog to /out/catalog.csv',
    rubric: '- /out/catalog.csv exists\n- The CSV has a header row with sku, name, and price columns\n- Every price value is a number'
  })
};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/outcomes', 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/v1/sessions/{session_id}/outcomes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'description' => 'Export the product catalog to /out/catalog.csv',
    'rubric' => '- /out/catalog.csv exists
- The CSV has a header row with sku, name, and price columns
- Every price value is a number'
  ]),
  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/v1/sessions/{session_id}/outcomes"

	payload := strings.NewReader("{\n  \"description\": \"Export the product catalog to /out/catalog.csv\",\n  \"rubric\": \"- /out/catalog.csv exists\\n- The CSV has a header row with sku, name, and price columns\\n- Every price value is a number\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/outcomes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"description\": \"Export the product catalog to /out/catalog.csv\",\n  \"rubric\": \"- /out/catalog.csv exists\\n- The CSV has a header row with sku, name, and price columns\\n- Every price value is a number\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/outcomes")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"description\": \"Export the product catalog to /out/catalog.csv\",\n  \"rubric\": \"- /out/catalog.csv exists\\n- The CSV has a header row with sku, name, and price columns\\n- Every price value is a number\"\n}"

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

{
  "agent_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "created_at": "2026-02-18T09:30:00.000Z",
  "defined_by_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "description": "example",
  "ended_at": "2026-02-18T09:30:00.000Z",
  "evaluations": [
    {
      "agent_version_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "cache_read_tokens": 1,
      "cache_write_tokens": 1,
      "cost_micros": 1,
      "criteria": [
        {
          "criterion_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "criterion_text": "example",
          "evidence_event_ids": [
            "example"
          ],
          "rationale": "example",
          "section": "example",
          "verdict": "example",
          "weight": 1.5
        }
      ],
      "end_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "ended_at": "2026-02-18T09:30:00.000Z",
      "explanation": "example",
      "grader_model_ref_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "grader_thread_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "input_tokens": 1,
      "iteration": 1,
      "outcome_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "output_tokens": 1,
      "result": "satisfied",
      "start_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "started_at": "2026-02-18T09:30:00.000Z"
    }
  ],
  "grader_model_ref_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "max_iterations": 1,
  "organization_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "outcome_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "rubric": "example",
  "rubric_ref": "example",
  "rubric_sha256": "example",
  "session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "status": "pending",
  "terminal_result": "satisfied",
  "updated_at": "2026-02-18T09:30:00.000Z"
}

{
  "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": "file_storage_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
  }
}

POST

managed-agents

sessions

{session_id}

outcomes

Define what done looks like for a session

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/outcomes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "Export the product catalog to /out/catalog.csv",
  "rubric": "- /out/catalog.csv exists\n- The CSV has a header row with sku, name, and price columns\n- Every price value is a number"
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/outcomes"

payload = {
    "description": "Export the product catalog to /out/catalog.csv",
    "rubric": "- /out/catalog.csv exists
- The CSV has a header row with sku, name, and price columns
- Every price value is a number"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    description: 'Export the product catalog to /out/catalog.csv',
    rubric: '- /out/catalog.csv exists\n- The CSV has a header row with sku, name, and price columns\n- Every price value is a number'
  })
};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/outcomes', 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/v1/sessions/{session_id}/outcomes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'description' => 'Export the product catalog to /out/catalog.csv',
    'rubric' => '- /out/catalog.csv exists
- The CSV has a header row with sku, name, and price columns
- Every price value is a number'
  ]),
  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/v1/sessions/{session_id}/outcomes"

	payload := strings.NewReader("{\n  \"description\": \"Export the product catalog to /out/catalog.csv\",\n  \"rubric\": \"- /out/catalog.csv exists\\n- The CSV has a header row with sku, name, and price columns\\n- Every price value is a number\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/outcomes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"description\": \"Export the product catalog to /out/catalog.csv\",\n  \"rubric\": \"- /out/catalog.csv exists\\n- The CSV has a header row with sku, name, and price columns\\n- Every price value is a number\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/outcomes")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"description\": \"Export the product catalog to /out/catalog.csv\",\n  \"rubric\": \"- /out/catalog.csv exists\\n- The CSV has a header row with sku, name, and price columns\\n- Every price value is a number\"\n}"

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

{
  "agent_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "created_at": "2026-02-18T09:30:00.000Z",
  "defined_by_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "description": "example",
  "ended_at": "2026-02-18T09:30:00.000Z",
  "evaluations": [
    {
      "agent_version_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "cache_read_tokens": 1,
      "cache_write_tokens": 1,
      "cost_micros": 1,
      "criteria": [
        {
          "criterion_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
          "criterion_text": "example",
          "evidence_event_ids": [
            "example"
          ],
          "rationale": "example",
          "section": "example",
          "verdict": "example",
          "weight": 1.5
        }
      ],
      "end_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "ended_at": "2026-02-18T09:30:00.000Z",
      "explanation": "example",
      "grader_model_ref_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "grader_thread_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "input_tokens": 1,
      "iteration": 1,
      "outcome_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "output_tokens": 1,
      "result": "satisfied",
      "start_event_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "started_at": "2026-02-18T09:30:00.000Z"
    }
  ],
  "grader_model_ref_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "max_iterations": 1,
  "organization_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "outcome_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "rubric": "example",
  "rubric_ref": "example",
  "rubric_sha256": "example",
  "session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "status": "pending",
  "terminal_result": "satisfied",
  "updated_at": "2026-02-18T09:30:00.000Z"
}

{
  "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": "file_storage_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.

Path Parameters

session_id

string<uuid>

required

Session id (UUID) as returned by startSession or listSessions.

Body

application/json

Option 1
Option 2

A definition of done for a session -- the task plus the rubric it is graded against. Accepted both when starting a session and when adding an outcome to a running one. Exactly one of rubric and rubric_ref is required.

description

string

required

The objective the agent works toward, and the statement of it the grader is given. It opens the session when the start request carries no message.

Minimum string length: 1

rubric

string

required

Markdown the grader scores the work against. Criteria must be independently checkable: 'the CSV has a numeric price column' can be verified, 'the data looks good' cannot. Send this or rubric_ref.

Minimum string length: 1

grader_model_ref_id

string

Model reference for the grader. Defaults to the session's model.

max_iterations

integer<int64>

default:0

Ceiling on grader passes before the outcome ends as max_iterations_reached. Omit it, or send 0, to revise until the grader is satisfied, which is the default. Set a number only to cap a rubric you are not sure can be met.

Required range: x >= 0

rubric_ref

object

The rubric as a file instead of inline markdown: the file's text is read once, when the outcome is defined, and recorded as the rubric. Exactly one of rubric and rubric_ref is required.

Show child attributes

Example:

{
  "file_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "type": "file"
}

Response

A session's definition of done: the task to achieve plus a rubric a grader scores the work against, tracked through its own grading lifecycle. Defined when the session starts, and read back to see whether the work was accepted.

created_at

string<date-time>

required

RFC 3339 timestamp of when this record was created. Server-assigned.

description

string

required

Objective the agent works toward, in prose, and the statement of it quoted to the grader. Opens the session when the start request carries no message.

max_iterations

integer<int64>

required

Ceiling on grader passes before the outcome ends as max_iterations_reached. Zero means unbounded, which is the default: the loop runs until the grader is satisfied.

organization_id

string

required

Organization that owns this record. Resolved from the API key; never accepted from the caller.

outcome_id

string

required

Identifier for this outcome (UUID). Server-assigned.

rubric

string

required

Markdown rubric the grader scores the work against. Write independently checkable criteria; vague criteria produce noisy revision loops.

session_id

string

required

Session this outcome belongs to (UUID).

status

enum<string>

required

Where the outcome is in its grading lifecycle: pending (no grader has looked at it), running (the agent is working toward it), evaluating (a grader pass is in flight), or terminal (grading finished; read terminal_result).

Available options:

pending,

running,

evaluating,

terminal

updated_at

string<date-time>

required

RFC 3339 timestamp of the last change to this record. Server-assigned.

agent_id

string

Agent this outcome belongs to (UUID), copied from the session that defined it.

defined_by_event_id

string

Event in the session's log that defined this outcome (UUID).

ended_at

string<date-time>

RFC 3339 timestamp of when grading reached a terminal result. Absent while the outcome is still open.

evaluations

object[]

Grader passes in order, newest last. Returned only by reads that ask for evaluations, and empty until a grader has run.

Show child attributes

grader_model_ref_id

string

Model reference the grader runs on (UUID), letting grading use a different model than the agent doing the work. Defaults to the session's model.

rubric_ref

string

Where the rubric text came from when it was not sent inline: file:<file_id> for a rubric read from a file when the outcome was defined. rubric always carries the text; later changes to the file do not move the bar.

rubric_sha256

string

Lowercase SHA-256 digest of the uploaded file the rubric was read from, for matching it to the file. Not a digest of rubric: the recorded text is the file's minus a byte-order mark and with line endings normalized.

terminal_result

enum<string>

Final verdict, set only once status is terminal: satisfied, max_iterations_reached, failed, or interrupted. Empty before then.

Available options:

satisfied,

max_iterations_reached,

failed,

interrupted

API reference

Endpoints

Define what done looks like for a session

Authorizations

Path Parameters

Body

Response