Get a setup run, optionally waiting for it to finish

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

import requests

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

headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/environments/{environment_id}/setup-runs/{setup_run_id}', 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/{setup_run_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$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/{setup_run_id}"

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

	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.get("https://api.recursion.labelbox.com/managed-agents/v1/environments/{environment_id}/setup-runs/{setup_run_id}")
  .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/{setup_run_id}")

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

request = Net::HTTP::Get.new(url)
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": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {}
}

GET

managed-agents

environments

{environment_id}

setup-runs

{setup_run_id}

Get a setup run, optionally waiting for it to finish

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

import requests

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

headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/environments/{environment_id}/setup-runs/{setup_run_id}', 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/{setup_run_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$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/{setup_run_id}"

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

	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.get("https://api.recursion.labelbox.com/managed-agents/v1/environments/{environment_id}/setup-runs/{setup_run_id}")
  .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/{setup_run_id}")

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

request = Net::HTTP::Get.new(url)
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": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

A Recursion API key, created in the console under API keys.

Path Parameters

environment_id

string<uuid>

required

Environment id (UUID).

setup_run_id

string<uuid>

required

Setup run id as returned by createEnvironmentSetupRun or the environment's setup_verification.active_setup_run_id.

Query Parameters

wait_seconds

integer

Block up to this many seconds for the run to reach succeeded, failed, or cancelled before responding. The server caps the wait at 5 seconds; larger values are accepted and clamped. 0 (the default) returns immediately and is recommended through the public API: sleep two seconds client-side and repeat to avoid timeouts on long-held requests.

Required range: 0 <= x <= 60

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

Get a setup run, optionally waiting for it to finish

Authorizations

Path Parameters

Query Parameters

Response