Run and verify the environment's setup script

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v2/environments/{environmentId}/setup-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "requestKind": "manual"
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v2/environments/{environmentId}/setup-runs"

payload = { "requestKind": "manual" }
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({requestKind: 'manual'})
};

fetch('https://api.recursion.labelbox.com/managed-agents/v2/environments/{environmentId}/setup-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/v2/environments/{environmentId}/setup-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([
    'requestKind' => 'manual'
  ]),
  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/v2/environments/{environmentId}/setup-runs"

	payload := strings.NewReader("{\n  \"requestKind\": \"manual\"\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/v2/environments/{environmentId}/setup-runs")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"requestKind\": \"manual\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v2/environments/{environmentId}/setup-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  \"requestKind\": \"manual\"\n}"

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

{
  "createdAt": "2023-11-07T05:31:56Z",
  "environmentId": "<string>",
  "kind": "<string>",
  "organizationId": "<string>",
  "setupRunId": "<string>",
  "status": "<string>",
  "computeId": "<string>",
  "computeProfile": {},
  "durationMs": 0,
  "exitCode": 0,
  "failedCommand": "<string>",
  "failedLine": 0,
  "failureCode": "<string>",
  "fingerprint": "<string>",
  "finishedAt": "2023-11-07T05:31:56Z",
  "gpuReadiness": {},
  "hint": "<string>",
  "hintCode": "<string>",
  "image": "<string>",
  "imageCapture": {
    "at": "2023-11-07T05:31:56Z",
    "setupRunId": "<string>",
    "status": "failed",
    "message": "<string>",
    "reason": "<string>"
  },
  "imageId": "<string>",
  "logBytes": 0,
  "logLines": 0,
  "logTruncated": true,
  "message": "<string>",
  "nextAction": {
    "method": "<string>",
    "operationId": "managedAgentsGetEnvironmentSetupRunLogV2",
    "path": "<string>"
  },
  "phase": "<string>",
  "providerRunId": "<string>",
  "requestedByUserId": "<string>",
  "sessionId": "<string>",
  "setupImage": {
    "baseImageDigest": "<string>",
    "capturedAt": "2023-11-07T05:31:56Z",
    "computeId": "<string>",
    "fingerprint": "<string>",
    "generation": 0,
    "image": "<string>",
    "imageId": "<string>",
    "runnerImage": "<string>",
    "setupRunId": "<string>",
    "sizeBytes": 0,
    "usable": true,
    "warmup": "<string>",
    "warmupMessage": "<string>"
  },
  "startedAt": "2023-11-07T05:31:56Z",
  "stderrTail": "<string>"
}

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

Environments

Run and verify the environment's setup script

Requires Idempotency-Key because this operation provisions billable compute. Provisions fresh compute for the environment, runs its setup script exactly as a session would (same image, resources, and variables; no session credentials), records every line of output, profiles the compute, releases it, and writes the verdict to the environment’s setupVerification. Returns 201 with the queued run; poll managedAgentsGetEnvironmentSetupRunV2 with waitSeconds until status is succeeded, failed, or cancelled. On failure read hint, failedLine, and stderrTail first, then the log. One run at a time per environment: a second request while one is in flight is a 409 naming the run to poll. Repeating the exact request with the same Idempotency-Key replays the original 201 response without starting another run. 400 when the environment has no setup script. This spends compute. When the tenant is out of credit, returns 403 setup_run_not_admitted with details.reason out_of_credit; buy credits and retry. A suspended tenant gets the same 403 with details.reason tenant_suspended. An unavailable credit check returns 503 setup_run_admission_unavailable without recording a run.

POST

managed-agents

environments

{environmentId}

setup-runs

Run and verify the environment's setup script

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v2/environments/{environmentId}/setup-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "requestKind": "manual"
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v2/environments/{environmentId}/setup-runs"

payload = { "requestKind": "manual" }
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({requestKind: 'manual'})
};

fetch('https://api.recursion.labelbox.com/managed-agents/v2/environments/{environmentId}/setup-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/v2/environments/{environmentId}/setup-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([
    'requestKind' => 'manual'
  ]),
  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/v2/environments/{environmentId}/setup-runs"

	payload := strings.NewReader("{\n  \"requestKind\": \"manual\"\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/v2/environments/{environmentId}/setup-runs")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"requestKind\": \"manual\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v2/environments/{environmentId}/setup-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  \"requestKind\": \"manual\"\n}"

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

{
  "createdAt": "2023-11-07T05:31:56Z",
  "environmentId": "<string>",
  "kind": "<string>",
  "organizationId": "<string>",
  "setupRunId": "<string>",
  "status": "<string>",
  "computeId": "<string>",
  "computeProfile": {},
  "durationMs": 0,
  "exitCode": 0,
  "failedCommand": "<string>",
  "failedLine": 0,
  "failureCode": "<string>",
  "fingerprint": "<string>",
  "finishedAt": "2023-11-07T05:31:56Z",
  "gpuReadiness": {},
  "hint": "<string>",
  "hintCode": "<string>",
  "image": "<string>",
  "imageCapture": {
    "at": "2023-11-07T05:31:56Z",
    "setupRunId": "<string>",
    "status": "failed",
    "message": "<string>",
    "reason": "<string>"
  },
  "imageId": "<string>",
  "logBytes": 0,
  "logLines": 0,
  "logTruncated": true,
  "message": "<string>",
  "nextAction": {
    "method": "<string>",
    "operationId": "managedAgentsGetEnvironmentSetupRunLogV2",
    "path": "<string>"
  },
  "phase": "<string>",
  "providerRunId": "<string>",
  "requestedByUserId": "<string>",
  "sessionId": "<string>",
  "setupImage": {
    "baseImageDigest": "<string>",
    "capturedAt": "2023-11-07T05:31:56Z",
    "computeId": "<string>",
    "fingerprint": "<string>",
    "generation": 0,
    "image": "<string>",
    "imageId": "<string>",
    "runnerImage": "<string>",
    "setupRunId": "<string>",
    "sizeBytes": 0,
    "usable": true,
    "warmup": "<string>",
    "warmupMessage": "<string>"
  },
  "startedAt": "2023-11-07T05:31:56Z",
  "stderrTail": "<string>"
}

{
  "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": "idempotency_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": "sandbox_provider_disabled",
  "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. 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.

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

environmentId

string<uuid>

required

Environment id (UUID) as returned by managedAgentsCreateEnvironment or managedAgentsListEnvironments.

Body

application/json

requestKind

enum<string>

required

write-only

Declare that this is a manually requested setup verification run.

Available options:

manual

Response

Created

createdAt

string<date-time>

required

read-only

When the run was requested.

environmentId

string

required

read-only

Environment whose setup ran.

kind

string

required

read-only

manual (requested through the API), runner_refresh (automatically captures an image for the current runner), or session (legacy in-session setup).

organizationId

string

required

read-only

Organization that owns the environment.

setupRunId

string

required

read-only

Server-assigned id of the run.

status

string

required

read-only

queued, provisioning, running, succeeded, failed, or cancelled. Poll until one of the last three; managedAgentsGetEnvironmentSetupRunV2 accepts waitSeconds to do that server-side.

computeId

string

read-only

Provider id of the compute the run used. Released when the run ends.

computeProfile

object

read-only

What the compute turned out to be: vCPUs, memory, GPUs, Docker state, image tools. Recorded after setup passed.

Show child attributes

durationMs

integer<int64>

read-only

Wall-clock duration in milliseconds, provisioning included.

Required range: -9007199254740991 <= x <= 9007199254740991

exitCode

integer

read-only

Exit code of the setup script when it ran. 124 means the timeout elapsed.

Required range: -9007199254740991 <= x <= 9007199254740991

failedCommand

string

read-only

The failing line's command as written, unexpanded.

failedLine

integer<int64>

read-only

1-based line in the setup script whose command exited non-zero. 0 when unknown.

Required range: -9007199254740991 <= x <= 9007199254740991

failureCode

string

read-only

Machine-readable failure class when the run did not succeed: environment_setup_failed, sandbox_capacity_unavailable, sandbox_gpu_not_ready, sandbox_provision_timeout, and so on. Same vocabulary as session failures.

fingerprint

string

read-only

Hash of the environment configuration the run executed.

finishedAt

string<date-time>

read-only

When the run reached a terminal status.

gpuReadiness

object

read-only

GPU readiness report for accelerator environments.

Show child attributes

hint

string

read-only

Likely fix when the failure cause is recognised.

hintCode

string

read-only

Stable identifier of the recognised failure cause.

image

string

read-only

Runner image the compute booted.

imageCapture

object

read-only

Capture failure recorded without changing the setup script verdict.

Show child attributes

imageId

string

read-only

Agent Service image id being captured.

logBytes

integer<int64>

read-only

Bytes of log persisted for the run.

Required range: -9007199254740991 <= x <= 9007199254740991

logLines

integer<int64>

read-only

Lines of log persisted for the run. The last line's seq equals this; pass it as after to tail.

Required range: -9007199254740991 <= x <= 9007199254740991

logTruncated

boolean

read-only

True when the script produced more output than the run keeps (4 MiB); the head and the stderr tail are retained.

message

string

read-only

One-sentence description of the outcome.

nextAction

object

read-only

The call that acts on this result: re-run setup after fixing the script, or fetch the log.

Show child attributes

phase

string

read-only

Current or final phase: provision, gpu_check, setup, profile, commit, cleanup.

providerRunId

string

read-only

Durable Agent Service run id executing the setup script.

requestedByUserId

string

read-only

User who requested a manual run.

sessionId

string

read-only

Session the run provisioned, for kind session.

setupImage

object

read-only

Immutable image published by this run when capture succeeded.

Show child attributes

startedAt

string<date-time>

read-only

When provisioning began.

stderrTail

string

read-only

Last lines of stderr, redacted and bounded to 2 KiB.

API reference

Endpoints

Run and verify the environment's setup script

Authorizations

Headers

Path Parameters

Body

Response