> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a setup run, optionally waiting for it to finish > Returns one setup run. With wait_seconds the call blocks until the run reaches a terminal status or the wait elapses, so a poll loop needs no client-side timer. next_action names the call to make on the result: poll again, read the log, or start a session. ## OpenAPI ````yaml /managed-agents/openapi.yaml get /managed-agents/v1/environments/{environment_id}/setup-runs/{setup_run_id} openapi: 3.1.0 info: title: Managed Agents API version: 0.13.0 description: >- The Recursion Managed Agents REST API. Authenticate with a Recursion API key as a bearer token. An organization-scoped key acts in its own organization and needs nothing else; a tenant-scoped key must also send `x-organization-id` with an organization id or `default`. Field names follow each operation's published schema. servers: - url: https://api.recursion.labelbox.com security: - bearerAuth: [] paths: /managed-agents/v1/environments/{environment_id}/setup-runs/{setup_run_id}: get: tags: - Environments summary: Get a setup run, optionally waiting for it to finish description: >- Returns one setup run. With wait_seconds the call blocks until the run reaches a terminal status or the wait elapses, so a poll loop needs no client-side timer. next_action names the call to make on the result: poll again, read the log, or start a session. operationId: managedAgentsGetEnvironmentSetupRun parameters: - description: >- 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. in: query name: wait_seconds schema: description: >- 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. maximum: 60 minimum: 0 type: integer - description: Environment id (UUID). in: path name: environment_id required: true schema: description: Environment id (UUID). format: uuid type: string - description: >- Setup run id as returned by createEnvironmentSetupRun or the environment's setup_verification.active_setup_run_id. in: path name: setup_run_id required: true schema: description: >- Setup run id as returned by createEnvironmentSetupRun or the environment's setup_verification.active_setup_run_id. format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsEnvironmentSetupRun' description: >- 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. '400': description: The request was rejected by schema or semantic validation. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '401': description: The caller is unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '403': description: The caller lacks a required permission or capability. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' '404': description: No such resource is reachable for this caller. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '429': headers: Retry-After: description: Seconds the caller should wait before retrying. schema: type: string style: simple description: A rate limit is exhausted. Honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '500': description: An unexpected server-side failure. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '502': description: The service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorBadGateway' '503': headers: Retry-After: description: Seconds the caller should wait before retrying. schema: type: string style: simple description: A dependency is unavailable. Retryable. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string description: The service did not respond before the timeout. Retryable. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorGatewayTimeout' components: schemas: ManagedAgentsEnvironmentSetupRun: description: >- 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. properties: compute_id: description: Provider id of the compute the run used. Released when the run ends. type: string compute_profile: additionalProperties: {} description: >- What the compute turned out to be: vCPUs, memory, GPUs, Docker state, image tools. Recorded after setup passed. type: object created_at: description: When the run was requested. format: date-time type: string duration_ms: description: Wall-clock duration in milliseconds, provisioning included. format: int64 type: integer environment_id: description: Environment whose setup ran. type: string exit_code: description: >- Exit code of the setup script when it ran. 124 means the timeout elapsed. type: integer failed_command: description: The failing line's command as written, unexpanded. type: string failed_line: description: >- 1-based line in the setup script whose command exited non-zero. 0 when unknown. format: int64 type: integer failure_code: description: >- 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. type: string fingerprint: description: Hash of the environment configuration the run executed. type: string finished_at: description: When the run reached a terminal status. format: date-time type: string gpu_readiness: additionalProperties: {} description: GPU readiness report for accelerator environments. type: object hint: description: Likely fix when the failure cause is recognised. type: string hint_code: description: Stable identifier of the recognised failure cause. type: string image: description: Runner image the compute booted. type: string imageCapture: $ref: '#/components/schemas/ManagedAgentsEnvironmentSetupImageCapture' description: Capture failure recorded without changing the setup script verdict. imageId: description: Agent Service image id being captured. type: string kind: description: >- manual (requested through the API to verify the environment) or session (performed while provisioning a session). type: string log_bytes: description: Bytes of log persisted for the run. format: int64 type: integer log_lines: description: >- Lines of log persisted for the run. The last line's seq equals this; pass it as after to tail. format: int64 type: integer log_truncated: description: >- True when the script produced more output than the run keeps (4 MiB); the head and the stderr tail are retained. type: boolean message: description: One-sentence description of the outcome. type: string next_action: $ref: '#/components/schemas/ManagedAgentsNextAction' description: >- The call that acts on this result: re-run setup after fixing the script, or fetch the log. organization_id: description: Organization that owns the environment. type: string phase: description: >- Current or final phase: provision, gpu_check, setup, profile, commit, cleanup. type: string providerEventCursor: description: >- Last Agent Service setup event sequence persisted into this run's log. format: int64 type: integer providerRunId: description: Durable Agent Service run id executing the setup script. type: string requested_by_user_id: description: User who requested a manual run. type: string session_id: description: Session the run provisioned, for kind session. type: string setup_run_id: description: Server-assigned id of the run. type: string setupImage: $ref: '#/components/schemas/ManagedAgentsEnvironmentSetupImage' description: Immutable image published by this run when capture succeeded. started_at: description: When provisioning began. format: date-time type: string status: description: >- queued, provisioning, running, succeeded, failed, or cancelled. Poll until one of the last three; getEnvironmentSetupRun accepts wait_seconds to do that server-side. type: string stderr_tail: description: Last lines of stderr, redacted and bounded to 2 KiB. type: string required: - organization_id - environment_id - setup_run_id - kind - status - created_at type: object example: 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 ManagedAgentsApiError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - analytics - analytics_not_ready - artifact_fetch_unavailable - artifact_generation_mismatch - artifact_hash_mismatch - artifact_invalid_events - artifact_invalid_json - artifact_not_allowlisted - artifact_size_mismatch - atomic_ingest_timeout - auth_unavailable - automation_event_source_invalid - automation_memory_unavailable - automation_reference_invalid - automation_runs_unconfigured - automations_unconfigured - bad_gateway - built_in_catalog_unavailable - built_in_integrations_unconfigured - compute_offerings_unavailable - conflict - content_store_request_canceled - content_store_unavailable - content_store_upload_timeout - credential_encryption_unconfigured - delegate_preparation_failed - entity_family_not_permitted - environment_not_verified - evaluation_cancellation_pending - evaluation_deletion_pending - event_admission_unavailable - event_ingress_unavailable - event_source_verification_credential_invalid - event_sources_unconfigured - execution_unconfigured - file_quota_exceeded - file_storage_unconfigured - forbidden - gateway_timeout - gestalt_unconfigured - github_rate_limited - github_unavailable - handoff_access_invalid - handoff_access_unavailable - handoff_access_unsupported - handoff_capture_unavailable - handoff_requires_retest - handoff_revoke_unavailable - handoff_signal_unavailable - idempotency_conflict - idempotency_in_progress - idempotency_unavailable - ingest_policy_changed - ingest_policy_not_found - ingest_policy_revoked - integrations_unconfigured - internal_error - invalid_json - invalid_pull_request_review_result - invalid_request - invalid_scope - invariant_violation - live_fleet_unconfigured - managed_agents_unavailable - missing_dependency - model_gateway_metadata_missing - model_gateway_unconfigured - model_gateway_unreachable - mutation_transaction_budget_exceeded - not_found - page_token_expired - payload_too_large - persistence_busy - precondition_failed - precondition_required - provider_registration_unsupported - provider_selection_unsupported - rate_limit_exceeded - rate_limited - repository_automation_unconfigured - request_too_large - reserved_source_type - revision_conflict - run_log_store_unavailable - runner_image_resolution_failed - sandbox_provider_disabled - service_unavailable - session_analyst_busy - session_analyst_model_unavailable - session_analyst_unconfigured - session_start_admission_unavailable - session_start_not_admitted - setup_fallback_environment_unsafe - setup_run_finished - setup_run_in_progress - setup_run_limit - setup_run_not_started - setup_runs_unavailable - skill_storage_unconfigured - slack_channels_rejected - slack_channels_unavailable - slack_channels_unconfigured - slack_connection_malformed - slack_event_intake_unavailable - slack_installation_mismatch - slack_missing_scope - slack_rate_limited - slack_reapproval_required - source_ownership_mismatch - source_revision_conflict - spanner_unavailable - streaming_unsupported - submission_transaction_budget_exceeded - task_version_number_conflict - team_board_unconfigured - too_many_streams - unauthorized - unsupported_media_type - vault_creation_retired - version_content_conflict - webhook_delivery_too_large - workspace_boundary_denied message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorForbidden: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - forbidden message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorBadGateway: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorGatewayTimeout: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - gateway_timeout message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsEnvironmentSetupImageCapture: description: Why a verified setup run published no new reusable image. properties: at: description: When the capture failure was recorded. format: date-time type: string message: description: Sanitized bounded explanation. type: string reason: description: Stable Agent Service capture failure reason. type: string setupRunId: description: Setup run whose capture failed. type: string status: description: Always failed; successful capture is represented by image. enum: - failed type: string required: - status - setupRunId - at type: object example: at: '2026-02-18T09:30:00.000Z' message: example reason: example setupRunId: example status: failed ManagedAgentsNextAction: description: >- The literal next API call to make. Included on errors and results whose resolution is one known call, so a caller need not infer it. properties: method: description: HTTP method of that call. type: string operation_id: description: >- OpenAPI operation id of the call to make next, e.g. createEnvironmentSetupRun. type: string path: description: Path of that call with path parameters already filled in. type: string required: - operation_id - method - path type: object example: method: example operation_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d path: example ManagedAgentsEnvironmentSetupImage: description: >- An immutable setup image published after a manual setup run passes. Identity includes the environment fingerprint, configured runner, observed base digest, and capture generation. properties: baseImageDigest: description: Immutable base image reference observed by Agent Service. type: string capturedAt: description: When Agent Service reported the image ready. format: date-time type: string computeId: description: Agent Service compute whose filesystem was captured. type: string fingerprint: description: Environment configuration fingerprint this image was produced for. type: string generation: description: Capture and boot contract generation. format: int64 type: integer image: description: Immutable digest-pinned image reference. type: string imageId: description: Agent Service image id. type: string runnerImage: description: Exact configured runner reference selected for the captured compute. type: string setupRunId: description: Manual setup run that produced this image. type: string sizeBytes: description: Captured filesystem layer size. format: int64 type: integer usable: description: >- Registry-free read-time projection for the active verified environment and configured runner. A moving tag may have changed since this projection; session admission resolves its exact digest before choosing the captured image or per-session setup. type: boolean warmup: description: >- Agent Service warmup state: pulling, verifying, ready, failed, or unavailable. type: string warmupMessage: description: Bounded Agent Service explanation of the warmup state. type: string required: - imageId - computeId - setupRunId - image - baseImageDigest - fingerprint - runnerImage - generation - sizeBytes - capturedAt type: object 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 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````