Start a simulation run for an automation

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/simulation-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "automationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "scenarios": {
    "scenarios": [
      {}
    ],
    "schemaVersion": 1
  },
  "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "allowWrites": false,
  "evaluatorAgentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/simulation-runs"

payload = {
    "automationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "scenarios": {
        "scenarios": [{}],
        "schemaVersion": 1
    },
    "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "allowWrites": False,
    "evaluatorAgentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    automationId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    scenarios: {scenarios: [{}], schemaVersion: 1},
    agentVersionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    allowWrites: false,
    evaluatorAgentId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/simulation-runs', 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/agents/{agentId}/simulation-runs",
  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([
    'automationId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'scenarios' => [
        'scenarios' => [
                [
                                
                ]
        ],
        'schemaVersion' => 1
    ],
    'agentVersionId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'allowWrites' => false,
    'evaluatorAgentId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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/agents/{agentId}/simulation-runs"

	payload := strings.NewReader("{\n  \"automationId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"scenarios\": {\n    \"scenarios\": [\n      {}\n    ],\n    \"schemaVersion\": 1\n  },\n  \"agentVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"allowWrites\": false,\n  \"evaluatorAgentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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/agents/{agentId}/simulation-runs")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"automationId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"scenarios\": {\n    \"scenarios\": [\n      {}\n    ],\n    \"schemaVersion\": 1\n  },\n  \"agentVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"allowWrites\": false,\n  \"evaluatorAgentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/simulation-runs")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"automationId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"scenarios\": {\n    \"scenarios\": [\n      {}\n    ],\n    \"schemaVersion\": 1\n  },\n  \"agentVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"allowWrites\": false,\n  \"evaluatorAgentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

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

{
  "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agentVersionId": "<string>",
  "allowWrites": true,
  "automationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "2023-11-07T05:31:56Z",
  "environmentId": "<string>",
  "episodeCount": 0,
  "failedCount": 0,
  "passedCount": 0,
  "runId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "scenariosDigest": "<string>",
  "status": "pending",
  "statusUrl": "<string>",
  "updatedAt": "2023-11-07T05:31:56Z",
  "completedAt": "2023-11-07T05:31:56Z",
  "costMicros": 0,
  "createdBy": "<string>",
  "error": {},
  "evaluatorAgentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

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

Simulations

Start a simulation run for an automation

Freezes the validated scenario batch into one run with one episode per scenario and starts the orchestration. Each episode admits its synthetic trigger through the automation’s production path and runs the requested agent version (the automation’s pinned version by default) against its real integrations with every non-read-only tool call recorded instead of executed, unless allowWrites opted into real writes. Within the organization-wide receipt namespace, Idempotency-Key plus the exact HTTP method, escaped path, raw query, and raw body bytes identify the durable result.

POST

managed-agents

agents

{agentId}

simulation-runs

Start a simulation run for an automation

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/simulation-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "automationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "scenarios": {
    "scenarios": [
      {}
    ],
    "schemaVersion": 1
  },
  "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "allowWrites": false,
  "evaluatorAgentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/simulation-runs"

payload = {
    "automationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "scenarios": {
        "scenarios": [{}],
        "schemaVersion": 1
    },
    "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "allowWrites": False,
    "evaluatorAgentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    automationId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    scenarios: {scenarios: [{}], schemaVersion: 1},
    agentVersionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    allowWrites: false,
    evaluatorAgentId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/simulation-runs', 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/agents/{agentId}/simulation-runs",
  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([
    'automationId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'scenarios' => [
        'scenarios' => [
                [
                                
                ]
        ],
        'schemaVersion' => 1
    ],
    'agentVersionId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'allowWrites' => false,
    'evaluatorAgentId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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/agents/{agentId}/simulation-runs"

	payload := strings.NewReader("{\n  \"automationId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"scenarios\": {\n    \"scenarios\": [\n      {}\n    ],\n    \"schemaVersion\": 1\n  },\n  \"agentVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"allowWrites\": false,\n  \"evaluatorAgentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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/agents/{agentId}/simulation-runs")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"automationId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"scenarios\": {\n    \"scenarios\": [\n      {}\n    ],\n    \"schemaVersion\": 1\n  },\n  \"agentVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"allowWrites\": false,\n  \"evaluatorAgentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/simulation-runs")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"automationId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"scenarios\": {\n    \"scenarios\": [\n      {}\n    ],\n    \"schemaVersion\": 1\n  },\n  \"agentVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"allowWrites\": false,\n  \"evaluatorAgentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

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

{
  "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agentVersionId": "<string>",
  "allowWrites": true,
  "automationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "2023-11-07T05:31:56Z",
  "environmentId": "<string>",
  "episodeCount": 0,
  "failedCount": 0,
  "passedCount": 0,
  "runId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "scenariosDigest": "<string>",
  "status": "pending",
  "statusUrl": "<string>",
  "updatedAt": "2023-11-07T05:31:56Z",
  "completedAt": "2023-11-07T05:31:56Z",
  "costMicros": 0,
  "createdBy": "<string>",
  "error": {},
  "evaluatorAgentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "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": "idempotency_unavailable",
  "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

required

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

agentId

string<uuid>

required

The agent whose automation is simulated.

Body

application/json

automationId

string<uuid>

required

The automation to simulate. Must belong to the agent in the path.

scenarios

object

required

Scenario batch document, schemaVersion 1: at most 20 scenarios, each one synthetic trigger input with optional checks, rubric and limits.

Show child attributes

agentVersionId

string<uuid>

The agent version to test. Must be a version of the automation's agent. Omitted, the run tests the automation's pinned version.

allowWrites

boolean

default:false

Execute integration writes for real instead of recording them. For sandbox tenants of the integrations only; requires the role that can edit the automation.

evaluatorAgentId

string<uuid>

Evaluator for scenario rubrics. Omitted, the simulated agent grades its own episodes through the hardened evaluation path.

Response

Accepted

agentId

string<uuid>

required

agentVersionId

string

required

allowWrites

boolean

required

Whether integration writes executed for real.

automationId

string<uuid>

required

createdAt

string<date-time>

required

environmentId

string

required

episodeCount

integer<int64>

required

Required range: -9007199254740991 <= x <= 9007199254740991

failedCount

integer<int64>

required

Required range: -9007199254740991 <= x <= 9007199254740991

passedCount

integer<int64>

required

Required range: -9007199254740991 <= x <= 9007199254740991

runId

string<uuid>

required

scenariosDigest

string

required

SHA-256 of the frozen scenario batch.

status

enum<string>

required

Run lifecycle. Episode verdicts, not run status, say whether the agent passed.

Available options:

pending,

running,

completed,

failed,

cancelled

statusUrl

string

required

Canonical member URL for polling this run.

updatedAt

string<date-time>

required

completedAt

string<date-time>

costMicros

integer

Aggregated cost of the episode and rubric grader sessions in micro-USD, recorded when the run settles. For a cancelled or failed run it is the spend known at settlement, while its sessions were still stopping.

Required range: -9007199254740991 <= x <= 9007199254740991

createdBy

string

error

object

Why the run failed, when it did.

Show child attributes

evaluatorAgentId

string<uuid>

API reference

Endpoints

Start a simulation run for an automation

Authorizations

Headers

Path Parameters

Body

Response