> ## 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 environment > Returns one environment and its full sandbox spec. A soft-deleted or unknown id is a 404, and an id belonging to another organization is reported the same way. ## OpenAPI ````yaml /recursion/openapi.yaml get /managed-agents/v1/environments/{environmentId} openapi: 3.1.0 info: title: Managed Agents API version: 0.14.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/{environmentId}: get: tags: - Environments summary: Get environment description: >- Returns one environment and its full sandbox spec. A soft-deleted or unknown id is a 404, and an id belonging to another organization is reported the same way. operationId: managedAgentsGetEnvironment parameters: - description: >- Environment id (UUID) as returned by managedAgentsCreateEnvironment or managedAgentsListEnvironments. in: path name: environmentId required: true schema: description: >- Environment id (UUID) as returned by managedAgentsCreateEnvironment or managedAgentsListEnvironments. format: uuid type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' responses: '200': content: application/json: schema: $ref: '#/components/schemas/Environment' description: >- A sandbox environment a session executes in: its provider, resources, mounts, setup steps and idle/delete lifecycle. Created and started independently of any session. headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' x-recursion-error-codes: - invalid_request headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' x-recursion-error-codes: - unauthorized headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' x-recursion-error-codes: - forbidden headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '404': description: Not Found. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' x-recursion-error-codes: - not_found headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '413': description: Payload Too Large. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' x-recursion-error-codes: - payload_too_large headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Too Many Requests. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' x-recursion-error-codes: - rate_limit_exceeded '500': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' x-recursion-error-codes: - internal_error headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '502': description: A dependent service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyFailure' x-recursion-error-codes: - bad_gateway headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '503': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Service Unavailable. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable x-recursion-error-codes: - managed_agents_unavailable - service_unavailable '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: A dependent service timed out. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyTimeout' x-recursion-error-codes: - gateway_timeout components: parameters: RecursionTenantId: name: x-tenant-id in: header required: false description: >- Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is `default`. schema: type: string minLength: 1 RecursionOrganizationId: name: x-organization-id in: header required: false description: >- 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`. schema: type: string minLength: 1 schemas: Environment: description: >- A sandbox environment a session executes in: its provider, resources, mounts, setup steps and idle/delete lifecycle. Created and started independently of any session. properties: computer_use: description: >- Whether this environment boots the shared interactive Chromium display used by the computer and human-handoff tools. The server projects this to http_port 6901. type: boolean config: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Provider-specific overflow settings this schema does not model. Passed to the provider unchanged. type: object created_at: description: >- Server-assigned RFC 3339 timestamp of when the environment was created. format: date-time readOnly: true type: string description: description: Free-text note about what this environment provides. type: string env_vars: additionalProperties: type: string description: >- Plaintext environment variables exported in the sandbox. They become the whole container environment, including the runner entrypoint's, so PATH is refused (env_vars.PATH): managed images select /workspace/.venv themselves. A Runs session using one-time setup after its runner changes also refuses startup-hook names such as BASH_ENV, HOME, PYTHONPATH, and LD_PRELOAD; re-test to capture a compatible image instead. Never put secrets here; store them as vault credentials instead. On update, omit to keep the current variables; send {} to clear them. type: object environment_id: description: >- Server-assigned id of the environment; pass it when starting a session that should run in this sandbox. readOnly: true type: string http_port: description: >- Port inside the sandbox to expose over HTTP for services the agent starts; 0 exposes nothing. format: int64 minimum: 0 type: integer maximum: 9007199254740991 idle_stop_after_seconds: description: >- Seconds of inactivity after which a running sandbox is stopped, from 120 to 2592000 (30 days); 0 uses the provider default. A computer-enabled environment requires 0 or at least 600 seconds so its five-minute handoff heartbeat arrives before idle-stop. format: int64 minimum: 0 type: integer maximum: 9007199254740991 image: description: >- Container image the sandbox boots. Set by the platform: new environments use the default runner image. Customize the sandbox itself with setup.script. type: string readOnly: true metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Caller-owned key/value data stored with the environment and returned unchanged. type: object mounts: description: >- Files or objects staged into the sandbox workspace when it is created. On update, omit to keep the current mounts; send [] to clear them. items: $ref: '#/components/schemas/EnvironmentMount' type: array name: description: Human-readable label shown wherever environments are listed. type: string network_policy: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Internet access for Runs environments. On update, omission keeps the current setting. Changing from another provider to Runs with an absent or {} saved policy requires an explicit network_policy: {"version":"v1","rules":[]} for No access or {} for unrestricted access. A nonempty policy limits destinations and cannot be combined with privileged Docker on create or when changing access settings. If the selected placement is incompatible, choose a compatible placement or send {} for unrestricted access. Send {} to clear a policy. Runs responses always include network_policy; {} means unrestricted. type: object organization_id: description: >- Organization that owns the environment. Server-assigned from the caller's credentials. readOnly: true type: string privileged: description: >- Whether a Runs sandbox may use privileged Docker. Privileged Docker requires unrestricted internet access (network_policy: {}) on create or when changing access settings. Omit on update to keep the current value, or send false to disable it. New Runs environments and transitions from another provider default to false. Existing environments with both limited internet access and privileged Docker remain visible and allow edits to other settings. To start a new session, set network_policy: {} or disable privileged Docker. type: boolean provider: description: >- Sandbox runtime that executes the session, chosen from the sandbox providers catalog. type: string pvc_size_gi: description: >- Size in GiB of the persistent workspace volume; 0 uses the provider default. format: int64 minimum: 0 type: integer maximum: 9007199254740991 resources: $ref: '#/components/schemas/EnvironmentResources' description: >- Caller-sized CPU and memory for CPU environments, or one exclusive accelerator with service-owned limits of 8,000 millicores (8 vCPU) and 32,768 MiB (32 GiB) of memory for GPU environments, plus lifetime and placement constraints. scope: description: >- Who may use the environment. Defaults to organization, meaning it is shared across the owning organization. type: string secrets: additionalProperties: type: string description: >- Deprecated and always empty for new environments. Environment secret references are no longer supported; use vault credentials instead. An environment stored with references cannot start sessions or setup runs until an update sends {} to clear them; clearing them marks the setup verdict stale, so re-test afterwards. type: object setup: $ref: '#/components/schemas/EnvironmentSetup' description: >- Setup script run after the sandbox is provisioned and before the agent starts. setup_updated_at: description: RFC 3339 timestamp of the last setup script change. Server-assigned. format: date-time readOnly: true type: string setup_updated_by_user_id: description: User who last changed the setup script. Server-assigned. readOnly: true type: string setup_verification: $ref: '#/components/schemas/EnvironmentSetupVerification' description: >- Server-owned verdict on the setup script: whether a manual or automatic setup run has proven this exact configuration on real compute. Read status and stale before starting sessions; read last_run.hint first when status is failed. readOnly: true setup_warnings: description: >- Advisory findings about the setup script (bash -lc wrapping, curl | sh, unpinned installs, ambiguous system Python, PATH replacement, or non-persistent shell activation), plus legacy_setup_discarded when the stored setup predates setup.script and is not run. Never block a save; computed on read. items: $ref: '#/components/schemas/EnvironmentSetupWarning' readOnly: true type: array stopped_delete_after_seconds: description: >- Seconds after a sandbox stops before it may be released, from 3600 (an hour) to 2592000 (30 days); 0 uses the service default. This does not expire the session. Send another message to resume it; /workspace files can be used when its workspace reopens. format: int64 minimum: 0 type: integer maximum: 9007199254740991 template: $ref: '#/components/schemas/TemplateRef' description: Reviewed template revision used to create this environment. updated_at: description: >- Server-assigned RFC 3339 timestamp of the most recent update to the environment. format: date-time readOnly: true type: string required: - organization_id - environment_id - name - scope - provider - setup - resources - computer_use - created_at - updated_at type: object additionalProperties: false ManagedAgentsApiErrorInvalidRequest: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_request message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnauthorized: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unauthorized message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. 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: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorNotFound: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - not_found message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPayloadTooLarge: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - payload_too_large message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimitExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limit_exceeded message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInternalError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - internal_error message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyFailure: 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: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorManagedAgentsUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - managed_agents_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorServiceUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - service_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyTimeout: 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: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. PlatformSafeJsonValue: description: >- A JSON value whose integer members stay within the exact ECMAScript safe-integer range at every nesting level. oneOf: - type: 'null' - type: boolean - type: string - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: number not: type: integer - type: array items: $ref: '#/components/schemas/PlatformSafeJsonValue' - additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object EnvironmentMount: additionalProperties: false description: >- One file or object staged into the sandbox workspace when it is created. Use mounts to give an agent input data it should find already on disk at the first turn. properties: mount_path: description: >- Absolute path inside the sandbox workspace where the source is placed. type: string source: description: Object or file to stage, as a URI the service can read. type: string type: object EnvironmentResources: additionalProperties: false description: >- Compute sizing and lifetime for an environment's sandbox. CPU environments accept caller-selected CPU and memory. GPU environments accept an exclusive accelerator plus optional lifetime and placement constraints, but use service-owned limits of 8,000 millicores (8 vCPU) and 32,768 MiB (32 GiB) of memory. properties: accelerator: $ref: '#/components/schemas/EnvironmentAccelerator' description: >- Exclusive GPU to attach to the sandbox compute. Omit for CPU-only. When set, the service applies limits of 8,000 millicores (8 vCPU) and 32,768 MiB (32 GiB) of memory, and cpu_milli and memory_mib must be omitted. cpu_milli: description: >- CPU request in millicores, so 1000 is one vCPU; 0 uses the provider default. CPU-only environments; must be omitted with an accelerator because the GPU sandbox CPU limit is service-owned. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 memory_mib: description: >- Memory request in MiB; 0 uses the provider default. CPU-only environments; must be omitted with an accelerator because the GPU sandbox memory limit is service-owned. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 placement: $ref: '#/components/schemas/EnvironmentPlacement' description: >- Optional region, provider, VRAM, spot, and price constraints. Without an egress policy, omission permits any configured provider. A nonempty Runs network_policy requires GKE; when placement is omitted, the runtime selects GKE without saving a placement constraint. timeout_seconds: description: >- Maximum sandbox lifetime in seconds before the provider tears it down; 0 uses the provider default. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 type: object EnvironmentSetup: additionalProperties: false description: >- Post-provision customization of a sandbox: a bash script run before the agent starts. Set it when the agent needs packages, tools, or state the runner image does not ship; leave it empty to start from the image as is. Verify it with a setup run before sessions use the environment. properties: script: description: >- Bash script run after the sandbox is provisioned and before the agent starts. Runs sessions boot from a captured setup image; when the runner changes, the platform runs this script on dedicated setup compute and captures a new image before provisioning the session. Executed as a separate login shell with set -eo pipefail, so the first failing line fails the run and is reported by line number; exports and activation do not persist into agent commands. Managed images automatically select a /workspace/.venv created here: install through its explicit interpreter and preserve the existing PATH. Do not wrap lines in bash -lc; the script already runs under bash. Empty means no setup. At most 64 KiB. type: string timeout_seconds: description: >- Wall-clock bound in seconds on the whole script; 0 uses the default of 600. Between 10 and 3600 when set. A run that exceeds it fails with exit code 124. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 type: object EnvironmentSetupVerification: description: >- Whether an environment's setup script has been proven to run on real compute. Server-owned: it is written by manual or automatic setup runs and never accepted from a request body. properties: active_setup_run_id: description: >- Manual or automatic setup run in flight for this environment, when there is one. Present alongside any status: a verified environment being re-verified stays verified, and sessions keep starting, until this run finishes. Follow it with managedAgentsGetEnvironmentSetupRun or managedAgentsGetEnvironmentSetupRunLog. Cleared when the run records a verdict or is cancelled. type: string at: description: RFC 3339 timestamp of when the recorded run finished. format: date-time type: string fingerprint: description: >- Hash of the environment configuration the run executed. Compared against the current configuration to derive stale; opaque to callers. type: string image: $ref: '#/components/schemas/EnvironmentSetupImage' description: >- Immutable compute image produced after setup passed. Session admission validates this capture and resolves the current runner before choosing to boot it or wait for an automatic runner_refresh capture. imageCapture: $ref: '#/components/schemas/EnvironmentSetupImageCapture' description: >- Most recent image capture failure. Independent from the setup verdict: setup can be verified while capture failed. last_run: $ref: '#/components/schemas/EnvironmentSetupRunSummary' description: >- Summary of the recorded run: exit code, failing line and command, stderr tail, and hint. Read hint first when the status is failed; it names the likely fix when the failure is a recognised one. setup_run_id: description: >- Setup run the status was written from. Read its log with managedAgentsGetEnvironmentSetupRunLog when the status is failed. type: string stale: description: >- True when the environment's provider, image, compute (resources, workspace disk size, provider config), setup script or timeout, variables, retired secret references, mounts, network policy, or privileged access changed after the recorded run, so the verdict no longer describes this configuration. Name, description, metadata, and the HTTP port do not count. Re-run setup to clear it. Always false for not_applicable and never. type: boolean status: description: >- not_applicable (no setup script), never (a script exists but no run has recorded a verdict), running (a setup run is in flight and there is no earlier passing verdict to stand on), verified (the latest recorded run passed), or failed (the latest recorded run failed). Sessions on managed providers require verified and not stale when a script is configured; Runs additionally requires a valid captured image. When the captured base differs from the runner resolved at session start, a runner_refresh setup run captures a matching image before session provisioning. The verdict is monotone: re-verifying a verified environment keeps it verified, with the new run in active_setup_run_id, until that run records its own verdict. type: string verified_by_user_id: description: User who requested the recorded run. type: string readOnly: true required: - status - stale type: object additionalProperties: false EnvironmentSetupWarning: description: >- An advisory finding about a setup script line. Warnings never block a save. properties: code: description: >- Stable identifier: bash_lc_wrapper, curl_pipe_sh, unpinned_install, rm_rf_root (line findings); or legacy_setup_discarded (line 0: the stored setup predates setup.script and does not run; re-enter it as a script). type: string line: description: >- 1-based script line the finding is on; 0 when the finding is about the save rather than a line. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 message: description: What was found and the recommended change. type: string required: - code - line - message type: object additionalProperties: false TemplateRef: description: Reviewed template id and revision copied into this resource. properties: id: description: Stable template id. type: string revision: description: Reviewed catalog revision. type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - revision type: object additionalProperties: false ManagedAgentsApiErrorDetails: type: object properties: field: description: >- Request field or header responsible for the error, when one can be identified. type: string issues: description: >- Boundary-validation failures as path-prefixed human-readable messages. type: array items: type: string requestId: description: Request correlation identifier for support and log lookup. type: string retryable: description: >- Server advice about failure transience. `true` means transient, `false` means non-transient, and absence gives no advice. Automatic replay is allowed only when this field is not `false` and the operation-specific retry and idempotency contract permits replay. type: boolean additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. EnvironmentAccelerator: additionalProperties: false description: >- An accelerator attached to an environment's sandbox compute. Set it only for GPU workloads; omit it and the sandbox runs CPU-only. A GPU sandbox receives one exclusive accelerator with service-owned limits of 8,000 millicores (8 vCPU) and 32,768 MiB (32 GiB) of memory; its host machine may be larger. properties: count: description: >- How many accelerators to attach. Defaults to 1; every offering currently carries one. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 name: description: >- Accelerator model, lower-case and provider-neutral, e.g. a100. Must name a model in this deployment's configured accelerator_catalog. Live compute offerings enrich that catalog but never remove configured choices. type: string type: description: Accelerator class to attach. Only gpu is accepted. type: string type: object EnvironmentPlacement: additionalProperties: false description: >- Where an environment's sandboxes may run, expressed as constraints rather than a named machine. The runtime selects a provider that can enforce the environment's access settings. properties: allow_spot: description: >- Let preemptible capacity compete on price. A reclaimed sandbox is failed and restarted from its last snapshot rather than resumed in place, so this trades an occasional lost turn for markedly cheaper accelerators. type: boolean max_price_per_hour_usd: description: >- Reject offerings priced above this per hour. Offerings whose price is unknown are never rejected by this, because an unpriced offering is a gap in a provider's catalog rather than an expensive machine. format: double type: number min_accelerator_vram_gb: description: >- Reject offerings whose per-accelerator memory is below this, in vendor-quoted gigabytes. Omit unless a workload genuinely needs the larger variant: an H100 and an H200 run the same image and the same snapshot, so treating them as interchangeable is what makes capacity findable. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 providers: description: >- Select exactly one provider, gke or nebius, when placement is present. Omit placement to let the system choose. Limited internet access is available only with gke. items: type: string type: array regions: description: >- Regions the sandbox may run in, as each provider names them. Empty means anywhere the deployment has configured, which is the usual answer: constraining regions constrains capacity, and capacity is the reason to place across providers at all. items: type: string type: array type: object EnvironmentSetupImage: description: >- An immutable setup image published after a manual or automatic 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 minimum: -9007199254740991 maximum: 9007199254740991 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 or automatic setup run that produced this image. type: string sizeBytes: description: Captured filesystem layer size. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 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 a runner refresh. 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 additionalProperties: false EnvironmentSetupImageCapture: 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 additionalProperties: false EnvironmentSetupRunSummary: description: >- The outcome of one setup run, reduced to what a caller needs to fix it: exit code, failing line, stderr tail, and a hint when the cause is recognised. properties: duration_ms: description: >- Wall-clock duration of the run in milliseconds, provisioning included. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 exit_code: description: >- Exit code of the setup script when it ran. 124 means the timeout elapsed; absent when the run failed before the script started. type: integer minimum: -9007199254740991 maximum: 9007199254740991 failed_command: description: >- The failing line's command as written in the script, unexpanded, so it never contains a secret's value. type: string failed_line: description: >- 1-based line in the setup script whose command exited non-zero. 0 when unknown. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 hint: description: >- Human-readable likely fix for a recognised failure cause. Absent rather than guessed when the cause is not recognised. type: string hint_code: description: >- Stable identifier of the recognised failure cause, e.g. command_not_found, pip_not_installed, bash_lc_wrapper, egress_blocked, timeout. Absent when the cause was not recognised. type: string message: description: One-sentence description of the outcome suitable for showing as is. type: string phase: description: >- Phase the run ended in: provision, gpu_check, setup, profile, commit, or cleanup. A failure outside setup is about the platform, not the script. type: string setup_run_id: description: Setup run this summary describes. type: string status: description: succeeded, failed, or cancelled. type: string stderr_tail: description: Last lines of stderr from the script, redacted and bounded to 2 KiB. type: string required: - setup_run_id - status type: object additionalProperties: false headers: RecursionOrganizationId: description: Organization id resolved for this request. schema: type: string minLength: 1 RecursionTenantId: description: Tenant id resolved for this request. schema: type: string minLength: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````