Define what done looks like for a session

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/sessions/{sessionId}/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/{sessionId}/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/{sessionId}/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/{sessionId}/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/{sessionId}/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/{sessionId}/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/{sessionId}/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

{
  "created_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "max_iterations": 0,
  "organization_id": "<string>",
  "outcome_id": "<string>",
  "rubric": "<string>",
  "session_id": "<string>",
  "status": "pending",
  "updated_at": "2023-11-07T05:31:56Z",
  "agent_id": "<string>",
  "ended_at": "2023-11-07T05:31:56Z",
  "evaluations": [
    {
      "iteration": 0,
      "outcome_id": "<string>",
      "result": "satisfied",
      "agent_version_id": "<string>",
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "cost_micros": 0,
      "criteria": [
        {
          "criterion_id": "<string>",
          "criterion_text": "<string>",
          "verdict": "<string>",
          "weight": 123,
          "evidence_event_ids": [
            "<string>"
          ],
          "rationale": "<string>",
          "section": "<string>"
        }
      ],
      "end_event_id": "<string>",
      "ended_at": "2023-11-07T05:31:56Z",
      "evaluationSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "explanation": "<string>",
      "input_tokens": 0,
      "output_tokens": 0,
      "start_event_id": "<string>",
      "started_at": "2023-11-07T05:31:56Z"
    }
  ],
  "historicalRoots": [
    {
      "createdAt": "2023-11-07T05:31:56Z",
      "evaluationSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "historyLimited": true,
      "rootStatus": "active",
      "executionState": "provisioning",
      "snapshotEventId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "stopReason": "<string>"
    }
  ],
  "passes": [
    {
      "evaluationSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "iteration": 0,
      "outcomeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "snapshotEventId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "startedAt": "2023-11-07T05:31:56Z",
      "status": "preparing",
      "endedAt": "2023-11-07T05:31:56Z",
      "failureReason": "<string>"
    }
  ],
  "rubric_ref": "<string>",
  "rubric_sha256": "<string>",
  "terminal_result": "satisfied"
}

{
  "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

{sessionId}

outcomes

Define what done looks like for a session

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/sessions/{sessionId}/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/{sessionId}/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/{sessionId}/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/{sessionId}/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/{sessionId}/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/{sessionId}/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/{sessionId}/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

{
  "created_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "max_iterations": 0,
  "organization_id": "<string>",
  "outcome_id": "<string>",
  "rubric": "<string>",
  "session_id": "<string>",
  "status": "pending",
  "updated_at": "2023-11-07T05:31:56Z",
  "agent_id": "<string>",
  "ended_at": "2023-11-07T05:31:56Z",
  "evaluations": [
    {
      "iteration": 0,
      "outcome_id": "<string>",
      "result": "satisfied",
      "agent_version_id": "<string>",
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "cost_micros": 0,
      "criteria": [
        {
          "criterion_id": "<string>",
          "criterion_text": "<string>",
          "verdict": "<string>",
          "weight": 123,
          "evidence_event_ids": [
            "<string>"
          ],
          "rationale": "<string>",
          "section": "<string>"
        }
      ],
      "end_event_id": "<string>",
      "ended_at": "2023-11-07T05:31:56Z",
      "evaluationSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "explanation": "<string>",
      "input_tokens": 0,
      "output_tokens": 0,
      "start_event_id": "<string>",
      "started_at": "2023-11-07T05:31:56Z"
    }
  ],
  "historicalRoots": [
    {
      "createdAt": "2023-11-07T05:31:56Z",
      "evaluationSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "historyLimited": true,
      "rootStatus": "active",
      "executionState": "provisioning",
      "snapshotEventId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "stopReason": "<string>"
    }
  ],
  "passes": [
    {
      "evaluationSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "iteration": 0,
      "outcomeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "snapshotEventId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "startedAt": "2023-11-07T05:31:56Z",
      "status": "preparing",
      "endedAt": "2023-11-07T05:31:56Z",
      "failureReason": "<string>"
    }
  ],
  "rubric_ref": "<string>",
  "rubric_sha256": "<string>",
  "terminal_result": "satisfied"
}

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

Headers

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

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 evaluator is given. It opens the session when the start request carries no message.

Minimum string length: 1

rubric

string

required

Markdown the evaluator 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

max_iterations

null | integer

default:5

Ceiling on evaluation passes. Omit or send null for five; send 0 explicitly for unbounded.

Required range: 0 <= x <= 9007199254740991

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

Response

A writer session's definition of done and its persisted evaluation-root verdicts.

created_at

string<date-time>

required

RFC 3339 timestamp when the outcome was created.

description

string

required

Objective the writer works toward, in prose.

max_iterations

integer<int64>

required

Maximum evaluator passes; zero explicitly means unbounded.

Required range: -9007199254740991 <= x <= 9007199254740991

organization_id

string

required

Organization that owns the outcome.

outcome_id

string

required

Server-assigned outcome identifier (UUID).

rubric

string

required

Markdown criteria used to evaluate the writer's work.

session_id

string

required

Writer session this outcome belongs to (UUID).

status

enum<string>

required

Current outcome lifecycle state, including evaluating while a root pass is in flight.

Available options:

pending,

running,

evaluating,

terminal

updated_at

string<date-time>

required

RFC 3339 timestamp of the latest outcome change.

agent_id

string

Writer agent that owns the outcome (UUID).

ended_at

string<date-time>

RFC 3339 timestamp when the outcome became terminal.

evaluations

object[]

Persisted evaluator passes in order, newest last.

Show child attributes

historicalRoots

object[]

Original cloned grader roots with no pass link or verdict; iteration and exact preparation start are unknown.

Show child attributes

passes

object[]

Cloned grading attempts, including preparation, failure, and interruption before a verdict exists.

Show child attributes

rubric_ref

string

Source file reference when the rubric was captured from an uploaded file.

rubric_sha256

string

SHA-256 digest of the source rubric file, when present.

terminal_result

enum<string>

Final outcome verdict; absent until terminal. not_applicable means no criterion applied and is not success.

Available options:

satisfied,

max_iterations_reached,

not_applicable,

failed

API reference

Endpoints

Define what done looks like for a session

Authorizations

Headers

Path Parameters

Body

Response