Run and verify the environment's setup script

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/environments/{environment_id}/setup-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>'

import requests

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

headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Idempotency-Key': '<idempotency-key>', Authorization: 'Bearer <token>'}
};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/environments/{environment_id}/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/v1/environments/{environment_id}/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_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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"
	"net/http"
	"io"
)

func main() {

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

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")

	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/environments/{environment_id}/setup-runs")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/environments/{environment_id}/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>'

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

{
  "compute_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "compute_profile": {
    "key": "example"
  },
  "created_at": "2026-02-18T09:30:00.000Z",
  "duration_ms": 1,
  "environment_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "exit_code": 1,
  "failed_command": "example",
  "failed_line": 1,
  "failure_code": "example",
  "fingerprint": "example",
  "finished_at": "2026-02-18T09:30:00.000Z",
  "gpu_readiness": {
    "key": "example"
  },
  "hint": "example",
  "hint_code": "example",
  "image": "example",
  "imageCapture": {
    "at": "2026-02-18T09:30:00.000Z",
    "message": "example",
    "reason": "example",
    "setupRunId": "example",
    "status": "failed"
  },
  "imageId": "example",
  "kind": "example",
  "log_bytes": 1,
  "log_lines": 1,
  "log_truncated": true,
  "message": "example",
  "next_action": {
    "method": "example",
    "operation_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
    "path": "example"
  },
  "organization_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "phase": "example",
  "providerEventCursor": 1,
  "providerRunId": "example",
  "requested_by_user_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "setupImage": {
    "baseImageDigest": "example",
    "capturedAt": "2026-02-18T09:30:00.000Z",
    "computeId": "example",
    "fingerprint": "example",
    "generation": 1,
    "image": "example",
    "imageId": "example",
    "runnerImage": "example",
    "setupRunId": "example",
    "sizeBytes": 1,
    "usable": true,
    "warmup": "example",
    "warmupMessage": "example"
  },
  "setup_run_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "started_at": "2026-02-18T09:30:00.000Z",
  "status": "example",
  "stderr_tail": "example"
}

{
  "code": "invalid_request",
  "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": "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, variables, and secrets; no session credentials), records every line of output, profiles the compute, releases it, and writes the verdict to the environment’s setup_verification. Returns 202 with the queued run; poll getEnvironmentSetupRun with wait_seconds until status is succeeded, failed, or cancelled. On failure read hint, failed_line, and stderr_tail 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 202 response without starting another run. 400 when the environment has no setup script. This spends compute.

POST

managed-agents

environments

{environment_id}

setup-runs

Run and verify the environment's setup script

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/environments/{environment_id}/setup-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>'

import requests

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

headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Idempotency-Key': '<idempotency-key>', Authorization: 'Bearer <token>'}
};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/environments/{environment_id}/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/v1/environments/{environment_id}/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_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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"
	"net/http"
	"io"
)

func main() {

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

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")

	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/environments/{environment_id}/setup-runs")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/environments/{environment_id}/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>'

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

{
  "compute_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "compute_profile": {
    "key": "example"
  },
  "created_at": "2026-02-18T09:30:00.000Z",
  "duration_ms": 1,
  "environment_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "exit_code": 1,
  "failed_command": "example",
  "failed_line": 1,
  "failure_code": "example",
  "fingerprint": "example",
  "finished_at": "2026-02-18T09:30:00.000Z",
  "gpu_readiness": {
    "key": "example"
  },
  "hint": "example",
  "hint_code": "example",
  "image": "example",
  "imageCapture": {
    "at": "2026-02-18T09:30:00.000Z",
    "message": "example",
    "reason": "example",
    "setupRunId": "example",
    "status": "failed"
  },
  "imageId": "example",
  "kind": "example",
  "log_bytes": 1,
  "log_lines": 1,
  "log_truncated": true,
  "message": "example",
  "next_action": {
    "method": "example",
    "operation_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
    "path": "example"
  },
  "organization_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "phase": "example",
  "providerEventCursor": 1,
  "providerRunId": "example",
  "requested_by_user_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "session_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "setupImage": {
    "baseImageDigest": "example",
    "capturedAt": "2026-02-18T09:30:00.000Z",
    "computeId": "example",
    "fingerprint": "example",
    "generation": 1,
    "image": "example",
    "imageId": "example",
    "runnerImage": "example",
    "setupRunId": "example",
    "sizeBytes": 1,
    "usable": true,
    "warmup": "example",
    "warmupMessage": "example"
  },
  "setup_run_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "started_at": "2026-02-18T09:30:00.000Z",
  "status": "example",
  "stderr_tail": "example"
}

{
  "code": "invalid_request",
  "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": "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: ^[!-~]+$

Path Parameters

environment_id

string<uuid>

required

Environment id (UUID) as returned by createEnvironment or listEnvironments.

Response

One execution of an environment's setup script on fresh compute: provision, GPU check, script, profile, image capture, cleanup. Read status until terminal, then hint, failed_line, and stderr_tail; the full log is a separate call.

created_at

string<date-time>

required

When the run was requested.

environment_id

string

required

Environment whose setup ran.

kind

string

required

manual (requested through the API to verify the environment) or session (performed while provisioning a session).

organization_id

string

required

Organization that owns the environment.

setup_run_id

string

required

Server-assigned id of the run.

status

string

required

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

compute_id

string

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

compute_profile

object

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

Show child attributes

duration_ms

integer<int64>

Wall-clock duration in milliseconds, provisioning included.

exit_code

integer

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

failed_command

string

The failing line's command as written, unexpanded.

failed_line

integer<int64>

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

failure_code

string

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

Hash of the environment configuration the run executed.

finished_at

string<date-time>

When the run reached a terminal status.

gpu_readiness

object

GPU readiness report for accelerator environments.

Show child attributes

hint

string

Likely fix when the failure cause is recognised.

hint_code

string

Stable identifier of the recognised failure cause.

image

string

Runner image the compute booted.

imageCapture

object

Capture failure recorded without changing the setup script verdict.

Show child attributes

Example:

{
  "at": "2026-02-18T09:30:00.000Z",
  "message": "example",
  "reason": "example",
  "setupRunId": "example",
  "status": "failed"
}

imageId

string

Agent Service image id being captured.

log_bytes

integer<int64>

Bytes of log persisted for the run.

log_lines

integer<int64>

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

log_truncated

boolean

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

message

string

One-sentence description of the outcome.

next_action

object

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

Show child attributes

Example:

{
  "method": "example",
  "operation_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "path": "example"
}

phase

string

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

providerEventCursor

integer<int64>

Last Agent Service setup event sequence persisted into this run's log.

providerRunId

string

Durable Agent Service run id executing the setup script.

requested_by_user_id

string

User who requested a manual run.

session_id

string

Session the run provisioned, for kind session.

setupImage

object

Immutable image published by this run when capture succeeded.

Show child attributes

Example:

{
  "baseImageDigest": "example",
  "capturedAt": "2026-02-18T09:30:00.000Z",
  "computeId": "example",
  "fingerprint": "example",
  "generation": 1,
  "image": "example",
  "imageId": "example",
  "runnerImage": "example",
  "setupRunId": "example",
  "sizeBytes": 1,
  "usable": true,
  "warmup": "example",
  "warmupMessage": "example"
}

started_at

string<date-time>

When provisioning began.

stderr_tail

string

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

Response