> ## 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. # Start a managed session > Starts a managed agent session and returns 202 with its session_id and status_path; the agent runs asynchronously, so poll getSession or subscribe with streamSessionEvents to follow it. Sandbox compute is provisioned here, which is where a session begins costing money. Requires an Idempotency-Key header: the same key with the same body returns the original session, and with a different body is rejected. A reasoning_effort incompatible with the selected model or its frozen output capacity returns 400 before provisioning; a temporarily unavailable model reference or catalog dependency returns 503. An environment on managed compute whose setup script has no verified, current run returns 422 environment_not_verified before provisioning; run createEnvironmentSetupRun first. ## OpenAPI ````yaml /managed-agents/openapi.yaml post /managed-agents/v1/sessions 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/sessions: post: tags: - Sessions summary: Start a managed session description: >- Starts a managed agent session and returns 202 with its session_id and status_path; the agent runs asynchronously, so poll getSession or subscribe with streamSessionEvents to follow it. Sandbox compute is provisioned here, which is where a session begins costing money. Requires an Idempotency-Key header: the same key with the same body returns the original session, and with a different body is rejected. A reasoning_effort incompatible with the selected model or its frozen output capacity returns 400 before provisioning; a temporarily unavailable model reference or catalog dependency returns 503. An environment on managed compute whose setup script has no verified, current run returns 422 environment_not_verified before provisioning; run createEnvironmentSetupRun first. operationId: managedAgentsStartSession parameters: - description: >- Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry. in: header name: Idempotency-Key required: true schema: description: >- Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry. maxLength: 256 minLength: 1 pattern: ^[!-~]+$ type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsStartSessionRequest' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsSessionCreatedResponse' description: >- Response body of POST /v1/sessions, returned with HTTP 202 and a Location header. The 202 is load-bearing: the session is accepted, not started, so no status, sandbox, or event exists yet and nothing here reports success of the run. Poll status_path, or stream events, to observe provisioning and execution. headers: Idempotency-Replayed: description: True when this response replays an earlier completed request. schema: type: boolean style: simple '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/ManagedAgentsApiErrorNotFound' '409': headers: Retry-After: description: Seconds to wait when a matching request is still in progress. schema: type: string style: simple description: >- The request conflicts with the resource state, or with an in-flight idempotent replay. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '413': description: The request exceeds a size or transaction budget. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '415': description: The request body uses a media type this operation does not accept. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' '422': description: The request is well formed but failed semantic validation. 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: ManagedAgentsStartSessionRequest: description: >- Request body for starting a session: which agent to run, the environment to run it in, the vault grants it receives, and the opening message and/or outcome that gives it work. properties: agent_id: description: >- The agent to run, from POST /v1/agents or GET /v1/agents. Its current version is snapshotted into the session, so later edits to the agent do not affect this run. type: string credential_refs: description: >- Optional per-item allowlist inside vault_ids. The list is a whitelist across every granted vault, not a filter within one, so it must name every item the session should receive. Omit with explicit vault_ids to enable all items; [] alongside a non-empty vault_ids is rejected because it would enable none. Omit both fields to use the agent version's defaults. items: $ref: '#/components/schemas/ManagedAgentsVaultCredentialRefRequest' type: array environment_id: description: >- The environment whose sandbox the session runs in, from POST /v1/environments or GET /v1/environments. Required for ordinary agents; evaluation agents omit it because the run has no parent sandbox and each child clones its target workspace. type: string evaluation: $ref: '#/components/schemas/ManagedAgentsEvaluationSelectorRequest' description: >- Target session snapshots for an evaluation agent. Set exactly one of session_ids or statuses plus limit; targets are resolved server-side within the caller's organization and public-session scope before the run is created. external_source_id: description: >- Stable identity inside the external system, e.g. a Slack thread key or a pull-request key. Set together with external_source_type. type: string external_source_type: description: >- Kind of external system this session correlates to, e.g. slack or github. Set together with external_source_id; sessions can then be filtered by both on GET /v1/sessions. type: string message: description: >- Opening user message for the session, and the context the agent works from. Send it alongside an outcome to supply facts the agent needs without making them part of what the grader measures; the grader never sees it. Kept in the session's system prompt for the whole run, so context compaction cannot summarize it away. type: string metadata: additionalProperties: type: string description: >- Caller-defined string key/value pairs stored on the session, e.g. ids that map it back to your own system. Write-once: they cannot be changed after start. At most 32 entries; keys use letters, digits, '_', '.', and '-' up to 64 characters; values are 1-512 characters without control characters. Returned as metadata on GET /v1/sessions and filterable with metadata=key:value (repeatable, AND) or metadata_key=key. maxProperties: 32 type: object outcome: $ref: '#/components/schemas/ManagedAgentsDefineOutcomeRequest' description: >- Optional definition of done, graded against a rubric. Its description is the objective and is quoted to the grader; send a message alongside it for context the grader should not see. With no message the description opens the session. Omit to inherit the agent version's default_rubric when it defines one, graded against this request's message; an outcome sent here is used as given and the agent default is ignored entirely. referenced_session_ids: description: >- Prior sessions this one may read, by session id. Each grants read access to the whole tree containing it -- transcript, agents, tools, cost, outcome, and output files -- through a set of read-only tools offered to the agent only when at least one reference exists. Each id is authorized under your own scope, so a session you cannot read refuses the whole request with 404 and starts nothing. Sessions from another organization, admin_only sessions, and session analysts are never referenceable. More may be added later with referenced_session_ids on POST /v1/sessions/{session_id}/events. items: type: string maxItems: 10 type: array resources: description: >- Files to mount read-only into the session's sandbox, under its files directory, before the first turn. Each attaches the file's content as it is now. All-or-nothing: one unknown or out-of-scope file_id refuses the whole request with 404 and creates nothing. Requires an environment with a sandbox. items: $ref: '#/components/schemas/ManagedAgentsSessionResourceRequest' maxItems: 500 type: array skip_default_outcome: description: >- Start ungraded even when the agent version defines a default_rubric. Only needed for an agent that has one, since omitting outcome otherwise inherits it. type: boolean team: $ref: '#/components/schemas/ManagedAgentsTeamRequest' description: >- How this session's tree may work as a team. Every tree has a shared task board: under mode auto (the default) the agent becomes a team the moment it posts its first task, recruiting copies of itself one per claimable task, which share its sandbox, claim work from the board, and are woken by its transitions; mode on makes it a team from turn one; mode off withholds the board. Overrides the agent's multiagent.team mode for this session; an agent with no roster runs under default limits. Governance (thread and cost caps) is the agent's and cannot be widened here. vault_ids: description: >- Vault grants for this session. Omit to use the agent version's default_vault_ids; send [] to disable all defaults. items: type: string type: array required: - agent_id type: object example: agent_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d credential_refs: - credential_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d vault_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d environment_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d evaluation: limit: 1 session_ids: - example statuses: - active external_source_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d external_source_type: example message: example metadata: key: example outcome: description: Export the product catalog to /out/catalog.csv rubric: |- - /out/catalog.csv exists - The CSV has a header row with sku, name, and price columns - Every price value is a number referenced_session_ids: - example resources: - file_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d mount_path: example relative_path: example type: file skip_default_outcome: true team: mode: auto vault_ids: - example ManagedAgentsSessionCreatedResponse: description: >- Response body of POST /v1/sessions, returned with HTTP 202 and a Location header. The 202 is load-bearing: the session is accepted, not started, so no status, sandbox, or event exists yet and nothing here reports success of the run. Poll status_path, or stream events, to observe provisioning and execution. properties: session_id: description: >- Identifier for this session (UUID). Server-assigned. Derived deterministically from the Idempotency-Key when one was sent, so a retried create returns the same id rather than starting a second session. type: string status_path: description: >- Path to poll for provisioning, execution, and structured failure state. type: string required: - session_id - status_path type: object example: session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d status_path: 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. 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: 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. ManagedAgentsVaultCredentialRefRequest: description: >- A pointer to one credential inside one vault. Used to grant a session specific credentials rather than every credential in a vault. properties: credential_id: description: Credential to select inside vault_id. type: string vault_id: description: >- Vault holding the credential. Required, because credential ids are unique only within a vault. type: string type: object example: credential_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d vault_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d ManagedAgentsEvaluationSelectorRequest: description: >- A bounded evaluation target selector: explicit session ids, or statuses plus a newest-first limit. properties: limit: description: Maximum newest matching sessions selected by statuses. maximum: 100 minimum: 1 type: integer session_ids: description: >- Explicit target session ids. Every id must be an eligible session visible to the caller or no run is created. items: type: string maxItems: 100 type: array statuses: description: >- Eligible target statuses. Used with limit to choose the newest matching sessions. items: $ref: '#/components/schemas/ManagedAgentsSessionStatus' type: array type: object example: limit: 1 session_ids: - example statuses: - active ManagedAgentsDefineOutcomeRequest: description: >- A definition of done for a session -- the task plus the rubric it is graded against. Accepted both when starting a session and when adding an outcome to a running one. Exactly one of rubric and rubric_ref is required. examples: - description: Export the product catalog to /out/catalog.csv rubric: |- - /out/catalog.csv exists - The CSV has a header row with sku, name, and price columns - Every price value is a number properties: description: description: >- The objective the agent works toward, and the statement of it the grader is given. It opens the session when the start request carries no message. type: string grader_model_ref_id: description: Model reference for the grader. Defaults to the session's model. type: string max_iterations: description: >- Ceiling on grader passes before the outcome ends as max_iterations_reached. Omit it, or send 0, to revise until the grader is satisfied, which is the default. Set a number only to cap a rubric you are not sure can be met. format: int64 type: integer rubric: description: >- Markdown the grader scores the work against. Criteria must be independently checkable: 'the CSV has a numeric price column' can be verified, 'the data looks good' cannot. Send this or rubric_ref. type: string rubric_ref: $ref: '#/components/schemas/ManagedAgentsOutcomeRubricRef' description: >- The rubric as a file instead of inline markdown: the file's text is read once, when the outcome is defined, and recorded as the rubric. Exactly one of rubric and rubric_ref is required. required: - description type: object example: description: Export the product catalog to /out/catalog.csv rubric: |- - /out/catalog.csv exists - The CSV has a header row with sku, name, and price columns - Every price value is a number ManagedAgentsSessionResourceRequest: description: One file to attach to a session. properties: file_id: description: >- The file to mount. Must belong to the caller's organization and not have expired. format: uuid type: string mount_path: description: >- The same place named absolutely, with the session's files directory as its root: /data/input.csv lands at data/input.csv, as does the directory's own absolute path copied from a session's resource list, and the /mnt/session/uploads/ prefix is accepted as an alias for the directory. Any other absolute root is likewise a path beneath the directory, never a mount elsewhere. Paths take the same shape rules as relative_path (no . or .. segments, no control characters, at most 255 characters); the filename's reserved-character rule does not apply to paths. Set this or relative_path; both are accepted only when they agree. type: string relative_path: description: >- Where the file lands relative to the session's files directory, e.g. data/input.csv. Defaults to the file's own name. Must be unique within the session and may not contain . or .. segments. type: string type: description: Always file. enum: - file type: string type: object example: file_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d mount_path: example relative_path: example type: file ManagedAgentsTeamRequest: description: >- Per-session override of the agent's team setting: whether the tree may become a team. Omit the mode to keep the agent's setting. The seats a team may fill are the roster's limits.max_concurrent_threads; recruits are sized to the claimable work under that cap, and teammates may always message each other directly. properties: mode: description: >- auto (default): the board tools are offered and the tree becomes a team when the agent posts its first task. on: a team from turn one, briefed as one before it has posted anything. off: no board; the agent delegates and waits as a plain coordinator. Omit to keep the agent's setting. enum: - auto - 'on' - 'off' type: string type: object example: mode: auto ManagedAgentsSessionStatus: description: Coarse session state shared by Managed Agents and imported RL rollouts. enum: - active - awaiting_human - completed - failed - cancelled type: string example: active ManagedAgentsOutcomeRubricRef: description: A file whose text is an outcome's rubric. properties: file_id: description: >- A file in the caller's organization holding the rubric: text or YAML, at most 256 KiB, uploaded through POST /v1/files. Its text is echoed back as the outcome's rubric. An unknown, expired, or out-of-scope file answers 404; a file that is not text, is oversized, is not UTF-8, or holds no criterion answers 400. format: uuid type: string type: description: Always file. enum: - file type: string required: - type - file_id type: object example: file_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: file securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````