> ## 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. # Open the session analyst for a session > Returns the caller's session analyst for the tree containing this session, starting one if they have none (201 when this call started it, 200 otherwise): a read-only assistant session that answers questions about the target -- what the agents were asked to do, what they did, which tools failed, how they coordinated, what it cost and how it was graded. Ask it questions by sending messages to the returned analyst session (sendSessionEvents) and read its answers from that session's events or event stream. One analyst per caller per tree: opening again returns the same conversation, and a body of {"reset": true} ends it; the next question starts a new one. The analyst runs on a fixed platform model with no sandbox and no credentials, and nothing it does changes the target session. Any session id in the tree is accepted; the analyst always reads the whole tree. ## OpenAPI ````yaml /managed-agents/openapi.yaml post /managed-agents/v1/sessions/{session_id}/analyst 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/sessions/{session_id}/analyst: post: tags: - Sessions summary: Open the session analyst for a session description: >- Returns the caller's session analyst for the tree containing this session, starting one if they have none (201 when this call started it, 200 otherwise): a read-only assistant session that answers questions about the target -- what the agents were asked to do, what they did, which tools failed, how they coordinated, what it cost and how it was graded. Ask it questions by sending messages to the returned analyst session (sendSessionEvents) and read its answers from that session's events or event stream. One analyst per caller per tree: opening again returns the same conversation, and a body of {"reset": true} ends it; the next question starts a new one. The analyst runs on a fixed platform model with no sandbox and no credentials, and nothing it does changes the target session. Any session id in the tree is accepted; the analyst always reads the whole tree. operationId: managedAgentsOpenSessionAnalyst parameters: - description: Session id (UUID) as returned by startSession or listSessions. in: path name: session_id required: true schema: description: Session id (UUID) as returned by startSession or listSessions. format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsOpenSessionAnalystRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsSessionAnalystResponse' description: >- Response body of openSessionAnalyst: the caller's read-only analyst session over a session tree, if there is one, and whether it was just started. '201': content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsSessionAnalystResponse' description: >- Response body of openSessionAnalyst: the caller's read-only analyst session over a session tree, if there is one, and whether it was just started. '400': description: The request was rejected by schema or semantic validation. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' discriminator: propertyName: code mapping: invalid_json: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' invalid_request: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' '401': description: The caller is unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' '403': description: The caller lacks a required permission or capability. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' - $ref: >- #/components/schemas/ManagedAgentsApiErrorWorkspaceBoundaryDenied discriminator: propertyName: code mapping: forbidden: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' workspace_boundary_denied: $ref: >- #/components/schemas/ManagedAgentsApiErrorWorkspaceBoundaryDenied '404': description: No such resource is reachable for this caller. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' '409': description: >- The request conflicts with the resource state, or with an in-flight idempotent replay. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorConflict' - $ref: '#/components/schemas/ManagedAgentsApiErrorRevisionConflict' discriminator: propertyName: code mapping: conflict: $ref: '#/components/schemas/ManagedAgentsApiErrorConflict' revision_conflict: $ref: >- #/components/schemas/ManagedAgentsApiErrorRevisionConflict '413': description: The request exceeds a size or transaction budget. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' '415': description: The request body uses a media type this operation does not accept. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string description: A rate limit is exhausted. Honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' '500': description: An unexpected server-side failure. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' - $ref: >- #/components/schemas/ManagedAgentsApiErrorInvariantViolation discriminator: propertyName: code mapping: internal_error: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' invariant_violation: $ref: >- #/components/schemas/ManagedAgentsApiErrorInvariantViolation '502': description: The service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorBadGateway' '503': description: >- A dependency is unavailable. Consult details.retryable and Retry-After when present before retrying. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorModelGatewayMetadataMissing - $ref: >- #/components/schemas/ManagedAgentsApiErrorModelGatewayUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorModelGatewayUnreachable - $ref: '#/components/schemas/ManagedAgentsApiErrorPersistenceBusy' - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionAnalystBusy - $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionAnalystModelUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionAnalystUnconfigured discriminator: propertyName: code mapping: content_store_unconfigured: $ref: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnconfigured managed_agents_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable model_gateway_metadata_missing: $ref: >- #/components/schemas/ManagedAgentsApiErrorModelGatewayMetadataMissing model_gateway_unconfigured: $ref: >- #/components/schemas/ManagedAgentsApiErrorModelGatewayUnconfigured model_gateway_unreachable: $ref: >- #/components/schemas/ManagedAgentsApiErrorModelGatewayUnreachable persistence_busy: $ref: >- #/components/schemas/ManagedAgentsApiErrorPersistenceBusy service_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable session_analyst_busy: $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionAnalystBusy session_analyst_model_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionAnalystModelUnavailable session_analyst_unconfigured: $ref: >- #/components/schemas/ManagedAgentsApiErrorSessionAnalystUnconfigured '504': description: The service did not respond before the timeout. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorGatewayTimeout' components: schemas: ManagedAgentsOpenSessionAnalystRequest: description: >- Optional request body of openSessionAnalyst. An empty body returns the caller's conversation with the tree, if any; question asks (starting the conversation if needed); reset ends the current conversation. properties: question: description: >- A question for the analyst. Starts the caller's conversation with this tree when there is none, as its first turn; otherwise it is delivered to the existing conversation. An analyst is never started without one. type: string reset: description: >- When true, ends the caller's current conversation with this tree: the analyst session is cancelled and stays readable, and the caller has no conversation until the next question. type: boolean type: object example: question: example reset: true ManagedAgentsSessionAnalystResponse: description: >- Response body of openSessionAnalyst: the caller's read-only analyst session over a session tree, if there is one, and whether it was just started. properties: created: description: >- True when this call started the analyst; false when it returned the caller's existing conversation with this tree, or none. type: boolean session: $ref: '#/components/schemas/ManagedAgentsSession' description: >- The analyst session, when the caller has a conversation with this tree. Send questions to it with sendSessionEvents and read answers from its events; its kind is session_analyst and its access policy platform_internal. Absent when nothing has been asked yet, or the conversation was just reset: a question starts one. required: - created type: object example: created: true session: access_policy: admin_only active_handoff: access_expires_at: '2026-02-18T09:30:00.000Z' deadline_at: '2026-02-18T09:30:00.000Z' handoff_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d reason: example requested_at: '2026-02-18T09:30:00.000Z' state: awaiting_user wake_cause: example agent_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d agent_snapshot: key: example agent_version_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d computer_use: true concurrency_slot_held: true config: key: example created_at: '2026-02-18T09:30:00.000Z' credential_refs: - credential_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d vault_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d credential_refs_configured: true effective_model: example environment_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d execution_state: provisioning external_source_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d external_source_type: example failure: at: '2026-02-18T09:30:00.000Z' category: transient code: example message: example phase: example retryable: true forked_at_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d kind: api_call last_activity_at: '2026-02-18T09:30:00.000Z' metadata: key: example model_ref_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d model_snapshot: key: example organization_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d parent_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d root_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sandbox_instance_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sandbox_provider: example session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d session_path: example source_refs: key: example status: active stop_reason: example tenant_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d updated_at: '2026-02-18T09:30:00.000Z' user_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d vault_ids: - example wake_at: '2026-02-18T09:30:00.000Z' ManagedAgentsApiErrorInvalidJson: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_json 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. 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. ManagedAgentsApiErrorWorkspaceBoundaryDenied: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - workspace_boundary_denied 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. ManagedAgentsApiErrorConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - conflict 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. ManagedAgentsApiErrorRevisionConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - revision_conflict 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. ManagedAgentsApiErrorInvariantViolation: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invariant_violation 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. 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: $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. ManagedAgentsApiErrorContentStoreUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - content_store_unconfigured 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. ManagedAgentsApiErrorModelGatewayMetadataMissing: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - model_gateway_metadata_missing 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. ManagedAgentsApiErrorModelGatewayUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - model_gateway_unconfigured 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. ManagedAgentsApiErrorModelGatewayUnreachable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - model_gateway_unreachable 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. ManagedAgentsApiErrorPersistenceBusy: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - persistence_busy 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. ManagedAgentsApiErrorSessionAnalystBusy: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - session_analyst_busy 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. ManagedAgentsApiErrorSessionAnalystModelUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - session_analyst_model_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. ManagedAgentsApiErrorSessionAnalystUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - session_analyst_unconfigured 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. 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: $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. ManagedAgentsSession: description: >- One durable agent run: its lifecycle status (active, awaiting_human, completed, failed, cancelled), the agent version, environment, model, and credentials it was pinned to, and its place in a multi-agent tree. Returned when starting, reading, or listing sessions; imported RL rollouts appear as sessions too and run no agent loop. properties: access_policy: description: >- Explicit access classification. Omitted/null is the ordinary behavior. admin_only requires elevated classified-data access and the current Admin organization role on public APIs. platform_internal is the service's own session over this organization's data: it is readable in-organization when addressed directly, but list and gestalt views include it only for callers with elevated classified-data access. enum: - admin_only - platform_internal type: string active_handoff: $ref: '#/components/schemas/ManagedAgentsActiveHandoff' description: >- Current browser handoff, including its exclusive driver claim and deadline. Absent when no browser handoff is active. Never contains the short-lived access URL. agent_id: description: >- Agent this session runs (UUID). Empty for imported sessions that were not started from an agent. type: string agent_snapshot: additionalProperties: {} description: >- The agent version's definition as it stood when the session started, frozen so later edits to the agent cannot change this session's behavior. type: object agent_version_id: description: >- Agent version this session runs (UUID), pinned at start so a later edit to the agent cannot change a running session. type: string computer_use: description: >- Whether this session has a computer-enabled environment and a display that passed its readiness probe. type: boolean concurrency_slot_held: description: >- Whether this root session currently occupies the agent's max_concurrent_sessions slot. True while admitted and non-terminal. False exclusively while an active queued root waits to start. Omitted for unlimited agents, child sessions, legacy rows, and terminal or deleted sessions. type: boolean config: additionalProperties: {} description: >- Resolved per-session runtime settings written at start, including the snapshotted MCP servers and tool bindings, multi-agent roster, and delegation depth limits. Read-only to callers. type: - object - 'null' created_at: description: RFC 3339 timestamp of when this record was created. Server-assigned. format: date-time type: string credential_refs: description: >- Explicit allowlist of individual credentials the session may use. Read credential_refs_configured to tell an intentionally empty allowlist from a legacy session granted whole vaults. items: $ref: '#/components/schemas/ManagedAgentsVaultCredentialRef' type: - array - 'null' credential_refs_configured: description: >- True when credential_refs is an explicit allowlist. False on legacy sessions granted every credential in their vaults, which would otherwise be indistinguishable from an empty allowlist. type: boolean effective_model: description: >- Provider-qualified model string frozen for this session, including any per-session model override. Prefer this over resolving model_ref_id or the current agent version when displaying what actually ran. type: string environment_id: description: Environment whose sandbox definition this session runs in (UUID). type: string execution_state: description: >- Where the agent loop is. Empty for sessions without a loop, such as imported rollouts. provisioning normally clears in under a minute and is bounded: a sandbox that does not become ready within the deployment's compute-ready timeout (five minutes by default) fails the session with sandbox_provision_timeout, so a session is never stuck here indefinitely. This field, read from the session itself, is the authoritative status -- a session's event stream is written on a separate path and can lag it, so an empty event list does not mean the session is still starting. When a session leaves provisioning by failing, failure carries the reason. enum: - provisioning - queued - running - idle - completed type: string external_source_id: description: >- Identifier of the session's counterpart in the external_source_type system, so a caller can find the session again from that side. Set together with external_source_type. type: string external_source_type: description: >- Kind of external system this session is correlated to, e.g. slack_thread. Set together with external_source_id and filterable when listing sessions. type: string failure: $ref: '#/components/schemas/ManagedAgentsSessionFailure' description: >- Structured terminal failure. Omitted for healthy sessions and legacy rows. forked_at_event_id: description: >- Event in the parent session (UUID) this session was forked from, so the fork's starting context is identifiable. Set only on forks. type: string kind: description: >- What produced the session: api_call, chat, rollout (an imported RL rollout), subagent (delegated by another session), benchmark, evaluation (a platform-started evaluation run over other session snapshots), reflection (a platform-started memory consolidation), or session_analyst (a platform-started read-only assistant that answers questions about another session tree). enum: - api_call - chat - rollout - subagent - benchmark - evaluation - reflection - session_analyst type: string last_activity_at: description: >- RFC 3339 timestamp of when the agent loop last made progress. Distinct from updated_at, which any metadata write touches. Absent for sessions that run no loop. format: date-time type: string metadata: additionalProperties: type: string description: >- Caller-defined string key/value pairs supplied when the session was started, e.g. ids from your own system. Immutable, present on root sessions only, and filterable with metadata=key:value or metadata_key=key on GET /v1/sessions. At most 32 entries; keys use letters, digits, '_', '.', and '-' up to 64 characters; values are 1-512 characters. type: object model_ref_id: description: >- Model reference the session's turns run on (UUID), resolved at start from the agent version or the start request. type: string model_snapshot: additionalProperties: {} description: >- The resolved model reference and inference settings as they stood when the session started, frozen for the same reason as agent_snapshot. type: object organization_id: description: >- Organization that owns this record. Resolved from the API key; never accepted from the caller. type: string parent_session_id: description: >- Session that created this one (UUID) — the delegating session for a subagent, or the source session for a fork. Empty on a root session. type: string root_session_id: description: >- Root session of the multi-agent tree this session belongs to (UUID). Equal to session_id for a root session. type: string sandbox_instance_id: description: >- Provider-assigned id of the sandbox instance serving this session. Empty before provisioning finishes; historical self_hosted sessions may also have no instance id. type: string sandbox_provider: description: >- Sandbox runtime that provisioned this session's compute, from the supported sandbox providers list. type: string session_id: description: Identifier for this session (UUID). Server-assigned. type: string session_path: description: >- Position of this session within its tree, as a slash-delimited path of session ids. "/" for a root session. type: string source_refs: additionalProperties: {} description: >- Secondary provenance ids from the originating system beyond the primary external source, e.g. an imported rollout's problem, problem-version, and run ids. type: object status: $ref: '#/components/schemas/ManagedAgentsSessionStatus' description: >- Coarse session state shared with RL rollout imports: active, awaiting_human (for a rollout, carries no score), completed, failed, or cancelled. For where a running agent loop is, read execution_state instead. stop_reason: description: >- Why the loop is not running. Set whenever execution_state is idle or completed. sleeping means the agent chose to wait and the session resumes on the next message or at wake_at; awaiting_subagents means a coordinator is waiting on delegated work. type: string tenant_id: description: >- Data-residency tenant the session's content is stored under, resolved from the request scope. A child session inherits its parent's value. type: string updated_at: description: >- RFC 3339 timestamp of the last change to this record. Server-assigned. format: date-time type: string user_id: description: >- User the session was started on behalf of, resolved from the request scope. Empty for sessions started by a service credential. type: string vault_ids: description: >- Vaults (UUIDs) the session may draw credentials from. Combine with credential_refs to narrow the grant to specific credentials. items: type: string type: array wake_at: description: >- RFC 3339 timestamp at which a sleeping session wakes itself if nobody messages it first. Absent unless the agent scheduled a timed wait. format: date-time type: string required: - root_session_id - session_path - session_id - organization_id - kind - status - computer_use - credential_refs - credential_refs_configured - config - created_at - updated_at type: object example: access_policy: admin_only active_handoff: access_expires_at: '2026-02-18T09:30:00.000Z' deadline_at: '2026-02-18T09:30:00.000Z' handoff_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d reason: example requested_at: '2026-02-18T09:30:00.000Z' state: awaiting_user wake_cause: example agent_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d agent_snapshot: key: example agent_version_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d computer_use: true concurrency_slot_held: true config: key: example created_at: '2026-02-18T09:30:00.000Z' credential_refs: - credential_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d vault_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d credential_refs_configured: true effective_model: example environment_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d execution_state: provisioning external_source_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d external_source_type: example failure: at: '2026-02-18T09:30:00.000Z' category: transient code: example message: example phase: example retryable: true forked_at_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d kind: api_call last_activity_at: '2026-02-18T09:30:00.000Z' metadata: key: example model_ref_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d model_snapshot: key: example organization_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d parent_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d root_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sandbox_instance_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sandbox_provider: example session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d session_path: example source_refs: key: example status: active stop_reason: example tenant_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d updated_at: '2026-02-18T09:30:00.000Z' user_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d vault_ids: - example wake_at: '2026-02-18T09:30:00.000Z' 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: {} description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. ManagedAgentsActiveHandoff: description: >- Public, credential-free state of a browser handoff that is awaiting a person, currently driven by one, or being resolved back to the agent. properties: access_expires_at: description: >- Latest time the current display access remains usable; never later than deadline_at. format: date-time type: string deadline_at: description: When the handoff automatically expires and the agent resumes. format: date-time type: string handoff_id: description: Stable identifier for this browser handoff. type: string reason: description: Why the agent asked a person to take over the shared browser. type: string requested_at: description: When the agent requested the handoff. format: date-time type: string state: description: >- Whether nobody has opened access yet, one person currently owns the display, or hand-back/deadline resolution is being delivered. enum: - awaiting_user - user_driving - resolved type: string wake_cause: description: >- Resolution cause once resolved: user_handed_back, deadline_elapsed, cancelled, or interrupted. type: string required: - handoff_id - reason - requested_at - deadline_at - state type: object example: access_expires_at: '2026-02-18T09:30:00.000Z' deadline_at: '2026-02-18T09:30:00.000Z' handoff_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d reason: example requested_at: '2026-02-18T09:30:00.000Z' state: awaiting_user wake_cause: example ManagedAgentsVaultCredentialRef: 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 required: - vault_id - credential_id type: object example: credential_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d vault_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d ManagedAgentsSessionFailure: description: >- Structured, sanitized reason a session terminated abnormally. Present on a session only after a terminal failure; healthy and legacy sessions omit it. properties: at: description: Time the terminal failure was persisted. format: date-time type: string category: description: >- Who can act on this failure: transient (wait or retry), caller_error (change the request or configuration, retrying as-is will not help), or internal (report it). retryable=false with category=caller_error is a fixable mistake, not an outage. A retryable failure is never caller_error: if the platform will retry, changing the request is not the fix. enum: - transient - caller_error - internal type: string code: description: Stable machine-readable failure code. type: string message: description: >- Sanitized bounded operator-facing message; never contains raw provider response bodies or credentials. type: string phase: description: >- Lifecycle phase that failed, such as provisioning, setup, workflow, or model. type: string retryable: description: >- Whether the platform will retry, or a retry of the same request may succeed on its own. False does not mean permanently broken -- read category to tell a transient condition from a request the caller must change. type: boolean required: - phase - code - message - retryable - category - at type: object example: at: '2026-02-18T09:30:00.000Z' category: transient code: example message: example phase: example retryable: true ManagedAgentsSessionStatus: description: Coarse session state shared by Managed Agents and imported RL rollouts. enum: - active - awaiting_human - completed - failed - cancelled type: string example: active securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````