> ## 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. # Cancel a setup run > Stops a queued or in-flight manual or automatic runner_refresh setup run and releases its compute. Sessions waiting on a cancelled runner_refresh fail with that run as their cause. The cancelled run is returned with status cancelled and active_setup_run_id is cleared. A cancelled run proves nothing: a standing verified or failed verdict is kept as it was, and an environment whose only verdict was running reverts to never. 409 when the run had already finished. ## OpenAPI ````yaml /recursion/openapi.yaml post /managed-agents/v1/environments/{environmentId}/setup-runs/{setupRunId}/cancel 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}/setup-runs/{setupRunId}/cancel: post: tags: - Environments summary: Cancel a setup run description: >- Stops a queued or in-flight manual or automatic runner_refresh setup run and releases its compute. Sessions waiting on a cancelled runner_refresh fail with that run as their cause. The cancelled run is returned with status cancelled and active_setup_run_id is cleared. A cancelled run proves nothing: a standing verified or failed verdict is kept as it was, and an environment whose only verdict was running reverts to never. 409 when the run had already finished. operationId: managedAgentsCancelEnvironmentSetupRun parameters: - description: Environment id (UUID). in: path name: environmentId required: true schema: description: Environment id (UUID). format: uuid type: string - description: >- Setup run id as returned by managedAgentsCreateEnvironmentSetupRun or the environment's setup_verification.active_setup_run_id. in: path name: setupRunId required: true schema: description: >- Setup run id as returned by managedAgentsCreateEnvironmentSetupRun or the environment's setup_verification.active_setup_run_id. format: uuid type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' responses: '200': content: application/json: schema: $ref: '#/components/schemas/EnvironmentSetupRun' 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. 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' '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorSetupRunFinished' x-recursion-error-codes: - setup_run_finished 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' '415': description: Unsupported Media Type. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' x-recursion-error-codes: - unsupported_media_type 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': 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 headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '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: EnvironmentSetupRun: 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: $ref: '#/components/schemas/PlatformSafeJsonValue' 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 minimum: -9007199254740991 maximum: 9007199254740991 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 minimum: -9007199254740991 maximum: 9007199254740991 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 minimum: -9007199254740991 maximum: 9007199254740991 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: $ref: '#/components/schemas/PlatformSafeJsonValue' 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/EnvironmentSetupImageCapture' 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), runner_refresh (automatically captures an image for the current runner), or session (legacy in-session setup). type: string log_bytes: description: Bytes of log persisted for the run. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 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 minimum: -9007199254740991 maximum: 9007199254740991 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/NextAction' 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 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/EnvironmentSetupImage' 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; managedAgentsGetEnvironmentSetupRun 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 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. ManagedAgentsApiErrorSetupRunFinished: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - setup_run_finished 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. ManagedAgentsApiErrorUnsupportedMediaType: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unsupported_media_type 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 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 NextAction: 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: type: string enum: - managedAgentsGetEnvironmentSetupRunLog - managedAgentsCreateEnvironmentSetupRun - managedAgentsStartSession - managedAgentsGetEnvironmentSetupRun description: Public Recursion operation id of the call to make next. path: type: string pattern: ^/managed-agents/v1(?:/|$) description: >- Canonical programmatic-host path with path parameters already filled in. required: - operation_id - method - path type: object additionalProperties: false 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 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. 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. ````