> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Get root session tree and timeline > Returns every session in the root session's tree, its threads, and the first bounded page of the merged chronological event log. When nextEventId is set, more events remain and should be fetched with managedAgentsListSessionEvents rather than by re-reading the tree. Any session id in the tree is accepted; the read resolves to its root. ## OpenAPI ````yaml /recursion/openapi.yaml get /managed-agents/v2/sessions/{sessionId}/tree openapi: 3.1.0 info: title: Managed Agents API version: 0.15.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/v2/sessions/{sessionId}/tree: get: tags: - Sessions summary: Get root session tree and timeline description: >- Returns every session in the root session's tree, its threads, and the first bounded page of the merged chronological event log. When nextEventId is set, more events remain and should be fetched with managedAgentsListSessionEvents rather than by re-reading the tree. Any session id in the tree is accepted; the read resolves to its root. operationId: managedAgentsGetSessionTreeV2 parameters: - description: >- Opt-in compatibility mode. images rehydrates private image refs under strict response caps; omitted by default. in: query name: hydrate schema: description: >- Opt-in compatibility mode. images rehydrates private image refs under strict response caps; omitted by default. enum: - images type: string x-recursion-omission: strategy: absent - description: >- Set to signed to add a short-lived url (and url_expires_at) to stored image blocks within the per-read signing budget. Omitted when signing is unavailable or the budget is exhausted; the authenticated managedAgentsGetSessionImage endpoint always works. in: query name: imageUrls schema: description: >- Set to signed to add a short-lived url (and url_expires_at) to stored image blocks within the per-read signing budget. Omitted when signing is unavailable or the budget is exhausted; the authenticated managedAgentsGetSessionImage endpoint always works. enum: - signed type: string x-recursion-omission: strategy: absent - description: >- External event payloads hydrate by default. Set refs to return bounded stubs and private reference metadata only. in: query name: payloads schema: description: >- External event payloads hydrate by default. Set refs to return bounded stubs and private reference metadata only. enum: - refs type: string x-recursion-omission: strategy: absent - description: >- Any session id (UUID) in the tree; the read resolves to its root session. in: path name: sessionId required: true schema: description: >- Any session id (UUID) in the tree; the read resolves to its root session. format: uuid type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' responses: '200': content: application/json: schema: $ref: '#/components/schemas/StandaloneV2TreeResult' description: OK headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' x-recursion-error-codes: - invalid_request headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' x-recursion-error-codes: - unauthorized headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' x-recursion-error-codes: - forbidden headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '404': description: Not Found. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' x-recursion-error-codes: - not_found headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '413': description: Payload Too Large. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' x-recursion-error-codes: - payload_too_large headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Too Many Requests. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' x-recursion-error-codes: - rate_limit_exceeded '500': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' x-recursion-error-codes: - internal_error headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '502': description: A dependent service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyFailure' x-recursion-error-codes: - bad_gateway headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '503': description: Service Unavailable. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: content_store_unavailable: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnavailable content_store_unconfigured: >- #/components/schemas/ManagedAgentsApiErrorContentStoreUnconfigured managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable x-recursion-error-codes: - content_store_unavailable - content_store_unconfigured - 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: minLength: 1 type: string 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: minLength: 1 type: string schemas: StandaloneV2TreeResult: properties: events: description: >- One page of the tree's events merged into a single chronological log across all sessions. Bounded by response size, so the page length is not a fixed count. items: $ref: '#/components/schemas/StandaloneV2Event' type: array nextEventId: description: >- Cursor to pass as the starting point of the next event page. Present only when more events remain; absent on the last page. type: string rootSessionId: description: >- Root session of the multi-agent tree this result covers (UUID). Equal to sessionId for a root session. type: string sessions: description: >- Every session in the tree, root and subagents alike. Always complete; only the event log is paged. items: $ref: '#/components/schemas/StandaloneV2Session' type: array threads: description: >- Thread registry rows for the tree's context-isolated execution streams. Imported RL children appear when their import supplied thread names; older imports without names use session-derived fallback rows. items: $ref: '#/components/schemas/StandaloneV2SessionThread' type: array required: - rootSessionId - sessions - threads - events type: object additionalProperties: false ManagedAgentsApiErrorInvalidRequest: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_request message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnauthorized: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unauthorized message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorForbidden: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - forbidden message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorNotFound: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - not_found message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPayloadTooLarge: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - payload_too_large message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimitExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limit_exceeded message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInternalError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - internal_error message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyFailure: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorContentStoreUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - content_store_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. 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. 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. StandaloneV2Event: properties: actor: description: >- Who produced this event, as a namespaced identifier: human:… for a person, system:… for the service itself, or an agent identity. type: string agentId: description: Agent that produced this event (UUID). type: string cacheReadTokens: description: >- Prompt tokens served from the provider's prompt cache, billed at the cached rate. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 cacheWriteTokens: description: Prompt tokens written into the provider's prompt cache. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 causalEventId: description: >- Event that caused this one (UUID). Unlike parent_event_id this expresses causality rather than nesting. type: string content: $ref: '#/components/schemas/StandaloneV2EventContent' description: >- The event payload as provider-shaped content blocks. Passed through to and from the model provider without reinterpretation. contentHydrationStatus: description: >- Read-time status when external EventContent was hydrated or could not be hydrated. enum: - hydrated - refs_only - missing - corrupt - unavailable - oversized type: string contentPayloadBytes: description: Byte size of the canonical external EventContent JSON. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 contentPayloadRef: description: >- Private whole-event content reference. Read the content through managedAgentsGetSessionEventContent; this reference cannot be fetched directly. type: string contentPayloadSha256: description: >- Lowercase SHA-256 digest of the canonical external EventContent JSON. type: string contentRef: description: >- Image cleanup prefix or typed multi-image envelope. This is independent of whole-event payload storage. type: string costMicros: description: >- Accrued cost in micro-USD (1,000,000 = 1 USD). Integer to avoid float rounding across many small charges. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 createdAt: description: RFC 3339 timestamp of when this record was created. Server-assigned. format: date-time type: string environmentId: description: Sandbox environment the producing session was executing in (UUID). type: string eventId: description: >- Identifier for this event (UUID). Server-assigned unless the append supplied one. Chronologically sortable, and the column a transcript is ordered by. type: string eventStatus: description: >- Outcome marker for events that can fail: pending, completed, warning, or error. Empty when not applicable. type: string eventType: description: >- What kind of event this is. One of message, tool_invocation, tool_result, approval_request, approval_decision, summary, plan_update, session_status, artifact, advisor_intervention, outcome_evaluation, or program_call. type: string finishReason: description: >- Why the provider stopped generating, in the provider vocabulary (for example end_turn, max_tokens, tool_use). Passed through verbatim. type: string inferenceConfig: $ref: '#/components/schemas/StandaloneV2InferenceConfig' description: >- Sampling and tool settings this inference ran with, as resolved at call time. inputTokens: description: Prompt tokens billed for this unit of work. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 latencyMs: description: Wall-clock duration of the provider call in milliseconds. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 model: $ref: '#/components/schemas/StandaloneV2ModelRef' description: >- Snapshot of the model reference as it was at call time, so a later model change does not rewrite history. modelRefId: description: >- Canonical model reference used for this inference (UUID). Empty on events not produced by a model call. type: string organizationId: description: >- Organization that owns this record. Resolved from the API key; never accepted from the caller. type: string outputTokens: description: Completion tokens billed for this unit of work. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 parentEventId: description: >- Event this one is nested under in the transcript tree (UUID), for example a tool result under its invocation. type: string promptTokens: description: >- Estimated tokens this event contributes when rendered into a future provider request. A memoized estimate for context-budget planning, not billed provider usage. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 providerModelId: description: >- Provider's own model identifier as sent on the wire, which may differ from the canonical model reference. type: string providerRequestId: description: >- Provider's request identifier for this inference, for correlating with provider-side logs. type: string providerType: description: >- Model provider family that served this inference, for example anthropic, openai, or vertex. type: string role: description: >- Message role in the provider vocabulary: system, user, or assistant. Set on message events; empty on events that are not turns. type: string sandboxInstanceId: description: >- Concrete sandbox instance the event was produced on. Provider-assigned, not a UUID. type: string schemaVersion: description: >- Event schema version this row was written under. Server-assigned; readers should tolerate unknown newer values. type: integer minimum: -9007199254740991 maximum: 9007199254740991 sessionId: description: Session this event belongs to (UUID). type: string threadId: description: >- Thread within a multi-agent session that produced this event (UUID). Empty on a single-agent session. type: string toolName: description: >- Name of the tool being invoked or reporting a result. Set on tool events only. type: string toolUseId: description: >- Provider's tool-call identifier, correlating a tool_invocation with its tool_result. type: string turnId: description: Groups every event produced within one model turn. type: string required: - schemaVersion - eventType - actor - content - inferenceConfig - sessionId - eventId - createdAt type: object additionalProperties: false StandaloneV2Session: properties: accessPolicy: type: string enum: - platform_internal description: >- Present only when reading a platform-managed session directly; these sessions are omitted from session lists. activeHandoff: $ref: '#/components/schemas/StandaloneV2ActiveHandoff' 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. agentId: description: >- Agent this session runs (UUID). Empty for imported sessions that were not started from an agent. type: string agentSnapshot: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- The definition of the agent version this session runs, frozen so later edits to the agent cannot change this session's behavior. Written at start; it changes only when the session moves to another version of its agent, which agentVersionId shows. type: object agentVersionId: description: >- Agent version this session runs (UUID), pinned at start so a later edit to the agent cannot change a running session. It changes only when the session moves to another version of its agent. type: string budget: $ref: '#/components/schemas/SessionBudgetStatus' description: >- The session tree's budget and what the tree has spent toward it, on a root session read in full. Omitted when the session has none, and on summary and list reads. computerUse: description: >- Whether this session has a computer-enabled environment and a display that passed its readiness probe. type: boolean concurrencySlotHeld: 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: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Resolved per-session runtime settings written at start, including the snapshotted MCP servers and tool bindings, multi-agent roster, and delegation depth limits. The settings an agent version owns change only when the session moves to another version of its agent. Read-only to callers. type: - object - 'null' costState: description: >- final once the session has ended, its sandbox has stopped, and every charge has settled: costUsd will not change unless the session is resumed. so_far while it can still grow. Present exactly when costUsd is. enum: - final - so_far type: string costUsd: description: >- Billed cost of this session's whole tree as an exact canonical decimal USD string. On Recursion, a writer's cost also includes linked cloned outcome evaluation roots, counting each ledger charge once; manual evaluations remain independent. On other surfaces, cost remains tree-only. Compute still running is included as an estimate; the figure is final once every included tree has ended and settled. Returned by managedAgentsGetSession and managedAgentsListSessions only, and absent when it cannot be read. examples: - '1.234567' type: string createdAt: description: RFC 3339 timestamp of when this record was created. Server-assigned. format: date-time type: string credentialRefs: description: >- Explicit allowlist of individual credentials the session may use; empty when none are listed. Read credentialRefsConfigured to tell an intentionally empty allowlist from a legacy session granted whole vaults. items: $ref: '#/components/schemas/StandaloneV2VaultCredentialRef' type: array credentialRefsConfigured: description: >- True when credentialRefs 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 effectiveModel: description: >- Provider-qualified model string this session runs, including any per-session model override. Written at start; it changes only when the session moves to another version of its agent. Prefer this over resolving model_ref_id or the current agent version when displaying the model a session runs. type: string environmentId: description: Environment whose sandbox definition this session runs in (UUID). type: string executionState: description: >- Where the agent loop is. Empty for sessions without a loop, such as imported rollouts. provisioning includes any automatic setup-image refresh before sandbox creation. The deployment's compute-ready timeout (five minutes by default) bounds sandbox readiness after refresh, not the setup run itself. A failed setup or sandbox timeout fails the session with the reason in failure. 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. enum: - provisioning - queued - running - idle - completed type: string externalSourceId: 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 externalSourceType: 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/SessionFailure' description: >- Structured terminal failure. Omitted for healthy sessions and legacy rows. forkedAtEventId: 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 lastActivityAt: 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 metadataAll=key:value or metadataKeyAll=key on GET /v2/sessions. At most 32 entries; keys use letters, digits, '_', '.', and '-' up to 64 characters; values are 1-512 characters. type: object modelRefId: description: >- Model reference the session's turns run on (UUID), resolved from the agent version or the start request. Written at start; it changes only when the session moves to another version of its agent. type: string modelSnapshot: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- The resolved model reference and inference settings this session runs, frozen for the same reason as agentSnapshot. Written at start; it changes only when the session moves to another version of its agent. type: object organizationId: description: >- Organization that owns this record. Resolved from the API key; never accepted from the caller. type: string parentSessionId: 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 projectId: description: >- Identifier of the external project the session's work belongs to, interpreted according to project_source. type: string rootSessionId: description: >- Root session of the multi-agent tree this session belongs to (UUID). Equal to sessionId for a root session. type: string sandboxInstanceId: 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 sandboxProvider: description: >- Sandbox runtime that provisioned this session's compute, from the supported sandbox providers list. type: string sessionId: description: Identifier for this session (UUID). Server-assigned. type: string sessionPath: description: >- Position of this session within its tree, as a slash-delimited path of session ids. "/" for a root session. type: string sourceRefs: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' 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/SessionStatus' 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. stopReason: 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; out_of_credit and tenant_suspended pause before new work and continue on the next message after the tenant is admitted again; an out_of_credit pause from the last 72 hours also continues on its own within about a minute once the tenant is admitted again; budget_reached means the session tree reached its budget and paused before its next model request, and raising or removing the session's budget continues it. type: string updatedAt: description: >- RFC 3339 timestamp of the last change to this record. Server-assigned. format: date-time type: string userId: description: >- User the session was started on behalf of, resolved from the request scope. type: string vaultIds: description: >- Vaults (UUIDs) the session may draw credentials from. Combine with credentialRefs to narrow the grant to specific credentials. items: type: string type: array wakeAt: 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: - rootSessionId - sessionPath - sessionId - organizationId - kind - status - computerUse - credentialRefs - credentialRefsConfigured - config - createdAt - updatedAt type: object additionalProperties: false StandaloneV2SessionThread: properties: agentId: description: Agent this thread runs (UUID). type: string agentVersionId: description: >- Agent version this thread runs (UUID). Absent when the thread was not pinned to a specific version. type: string archivedAt: description: >- RFC 3339 timestamp of when this thread was archived and stopped appearing as an active stream. Absent while the thread is not archived. format: date-time type: string createdAt: description: RFC 3339 timestamp of when this record was created. Server-assigned. format: date-time type: string name: description: >- Human-readable label for this thread, supplied when it was spawned. Optional and never interpreted by the service. type: string parentSessionId: description: >- Session the spawning thread belongs to (UUID). Absent on the tree's top-level thread. type: string parentThreadId: description: >- Thread that spawned this one (UUID). Absent on the tree's top-level thread. type: string role: description: >- What the thread exists to do within the tree, for example subagent, grader, or advisor. Not a chat message role. type: string rootSessionId: description: >- Root session of the multi-agent tree this thread belongs to (UUID). Equal to sessionId for a root session. type: string sessionId: description: Session this thread belongs to (UUID). type: string sessionPath: description: >- Slash-joined ancestry of session ids from the tree root down to the session whose events this thread's events are stored under, for example "/root-id/child-id". type: string status: description: >- Thread lifecycle: running (executing now), idle (awaiting more input), or terminated (finished; see stop_reason). type: string stopReason: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Structured reason the thread last stopped, forwarded from the agent loop, for example {"type": "end_turn"} or {"type": "error", "message": ...}. Absent while the thread has not stopped. type: object threadId: description: >- Identifier for this thread within its session tree (UUID). Server-assigned. For a subagent thread it is the child session id, so the thread and the session carrying its events resolve each other directly. type: string threadPath: description: >- Slash-joined ancestry of this thread within the tree, used to order threads for display. Defaults to session_path when the thread has no deeper nesting of its own. type: string updatedAt: description: >- RFC 3339 timestamp of the last change to this record. Server-assigned. format: date-time type: string required: - rootSessionId - sessionPath - threadId - sessionId - agentId - threadPath - role - status - createdAt - updatedAt 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. StandaloneV2EventContent: properties: assistantInteraction: $ref: '#/components/schemas/AssistantInteraction' description: >- One state of a typed request an assistant put in front of the reader: questions, a solution blueprint, or a plan of changes. Present on the approval_request events of an assistant session, one per state the interaction passes through. blocks: description: >- Ordered content blocks of this message, in the provider's content-block form. Empty for events that carry no message body. items: $ref: '#/components/schemas/StandaloneV2ContentBlock' type: array evaluationBudgetReached: $ref: '#/components/schemas/StandaloneV2EvaluationBudgetReached' description: >- Cost cap and targets stopped or left unadmitted when the run reached it. evaluationPlanFrozen: $ref: '#/components/schemas/StandaloneV2EvaluationPlanFrozen' description: >- Frozen target, rubric, concurrency, and cost plan for an evaluation run. evaluationRunFinished: $ref: '#/components/schemas/StandaloneV2EvaluationRunFinished' description: Terminal counts and systemic failure state for the evaluation run. evaluationTargetSkipped: $ref: '#/components/schemas/StandaloneV2EvaluationTargetSkipped' description: >- Sanitized outcome for a target whose processing ended without a completed verdict audit. evaluationTargetStarted: $ref: '#/components/schemas/StandaloneV2EvaluationTargetStarted' description: Identity and clone state for one admitted evaluation target. evaluationVerdictRecorded: $ref: '#/components/schemas/StandaloneV2EvaluationVerdictRecorded' description: Audit reference to one authoritative immutable evaluation verdict. metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Extra key/value detail about this event that is not part of the message body, such as the ingest subtype or the sandbox working directory. type: object plan: description: Plan items reported by the agent, present on a plan_update event. items: $ref: '#/components/schemas/PlanItem' type: array stopReason: description: >- The provider's own stop_reason for the assistant turn, recorded verbatim, e.g. end_turn, tool_use, or max_tokens. Absent on events that are not a model response. type: string tools: description: >- Tool definitions that were in scope for the turn, as sent to the provider. Recorded on the session's system message so a transcript shows what the model could call. items: $ref: '#/components/schemas/StandaloneV2ToolDefinition' type: array usage: $ref: '#/components/schemas/StandaloneV2Usage' description: >- Token counts the provider reported for the call that produced this message. Absent when the event is not a model response. required: - blocks type: object additionalProperties: false StandaloneV2InferenceConfig: properties: maxTokens: description: >- Upper bound on tokens the model may generate for one assistant turn (the provider's max_tokens). Omit or 0 to use the model reference's default. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 providerParams: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Recognized provider-specific settings are thinking, thinkingDisplay and output_config for native Anthropic messages; thinkingConfig for native Gemini; and promptCache, promptCacheTTL and promptCacheSharedTTL for prompt caching. Unknown top-level keys are ignored, not passed through. Omitting all three cache settings enables automatic policy: explicit caching stays enabled and eligible Anthropic requests may use 1h shared retention when recent usage and current pricing evidence predict savings; otherwise shared retention is 5m. Setting promptCache or either TTL explicitly keeps operator-configured retention. promptCache true enables explicit markers; false disables them and ignores both TTL settings. With caching enabled, both TTL settings accept only 5m or 1h on models using native Anthropic messages. promptCacheTTL defaults to 5m for user-context anchors and history. promptCacheSharedTTL controls tools and system instructions, defaults to promptCacheTTL under explicit configuration, and cannot be shorter than promptCacheTTL. Authored thinking objects and enabled cache TTL settings are validated at agent/version writes and session start. type: object reasoningEffort: description: >- Provider-native reasoning depth value. For a model from the models catalog, use one of its supportedReasoningEfforts; omit it to follow the provider's current default. type: string temperature: description: >- Sampling temperature passed through to the provider, typically 0.0-2.0. Lower values are more deterministic. Omit to use the provider default. type: number topP: description: >- Nucleus-sampling probability mass (0.0-1.0) passed through to the provider. Prefer setting either this or temperature, not both. Omit to use the provider default. type: number type: object additionalProperties: false StandaloneV2ModelRef: properties: baseUrl: description: >- Endpoint the request was sent to, for models not served at their provider's default endpoint. Empty means the provider's default endpoint. type: string capabilities: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Declared model capability flags, e.g. tool use, vision, or extended thinking support, as recorded from the catalog entry at call time. type: object contextWindow: description: >- Maximum total tokens the model accepts in one request, prompt plus completion, as recorded from the catalog entry at call time. 0 means unknown. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 maxOutputTokens: description: >- Maximum completion tokens the model can emit in one response, as recorded from the catalog entry at call time. 0 means unknown. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Extra key/value data copied from the catalog entry. Some keys are read by the service to shape the request, such as base_url and reasoning_style. type: object model: description: >- Provider's own model id as sent on the wire, e.g. model-name or provider/model-name. type: string modelRefId: description: >- Model reference in the catalog this snapshot was resolved from (UUID). Empty when the session named a models-catalog id instead of a catalog entry. type: string modelVersion: description: >- Provider-specific version or snapshot pin recorded alongside the model id, when the catalog entry declares one. type: string provider: description: >- Provider family that served the call, e.g. anthropic, openai, vertex, or mock. Carries the same value as provider_type and is kept for older readers. type: string providerId: description: >- Model provider record whose credentials and base URL were used (UUID). type: string providerType: description: >- Provider family that served the call, e.g. anthropic, openai, vertex, or mock. Selects which wire protocol the request used. type: string servingBackend: description: >- Serving stack behind a self-hosted model, e.g. vllm. Empty for models called through a hosted provider API. type: string required: - provider - model type: object additionalProperties: false StandaloneV2ActiveHandoff: properties: accessExpiresAt: description: >- Latest time the current display access remains usable; never later than deadline_at. format: date-time type: string deadlineAt: description: When the handoff automatically expires and the agent resumes. format: date-time type: string handoffId: 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 requestedAt: 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 wakeCause: description: >- Resolution cause once resolved: user_handed_back, deadline_elapsed, cancelled, or interrupted. type: string required: - handoffId - reason - requestedAt - deadlineAt - state type: object additionalProperties: false 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 SessionBudgetStatus: description: A session tree's budget and what it has spent toward it. properties: agentCapUsd: description: >- The agent's multiagent.limits.max_tree_cost_usd, in US dollars with two decimals: the most this budget can be set to. A session whose budget reached it stays paused; start a new session, or raise the agent's cap for sessions started after. examples: - '25.00' readOnly: true type: string continuesOnRaise: description: >- Whether raising or removing the budget of a session paused at it continues the session right away. False for a session bound to a Slack thread, which continues on its next reply there. readOnly: true type: boolean maxCostUsd: description: The budget in US dollars, with two decimals. examples: - '10.00' pattern: ^(0|[1-9][0-9]{0,5})(\.[0-9]{1,2})?$ type: string spentUsd: description: >- What the session tree has spent, plus any linked outcome grading sessions charged to the same budget on Recursion, in US dollars with two decimals, at the billed price the budget is enforced at (models, tools and sandbox compute). Present on a full read of the root; absent when the spend could not be read. A session that paused at its budget can read a little past it: the request that crossed it completes. examples: - '4.20' readOnly: true type: string required: - maxCostUsd - continuesOnRaise type: object additionalProperties: false StandaloneV2VaultCredentialRef: properties: credentialId: description: Credential to select inside vault_id. type: string vaultId: description: >- Vault holding the credential. Required, because credential ids are unique only within a vault. type: string required: - vaultId - credentialId type: object additionalProperties: false SessionFailure: 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 additionalProperties: false SessionStatus: description: Coarse session state shared by Managed Agents and imported RL rollouts. enum: - active - awaiting_human - completed - failed - cancelled type: string AssistantInteraction: description: >- A typed request for the reader's input that an assistant put in front of them: questions, a solution blueprint, or a plan of changes. Each state is recorded as one event; the latest event per interactionId is the current state. properties: blueprint: $ref: '#/components/schemas/AssistantBlueprint' description: The solution design, on a blueprint interaction. decision: $ref: '#/components/schemas/AssistantDecision' description: The person's decision, once one was made. digest: description: >- Digest of this revision's content. A decision names it so a person decides exactly what they were shown. type: string interactionId: description: >- Stable id of the interaction. Revisions of a blueprint or plan keep it. type: string kind: description: >- What is being asked: questions, a solution blueprint, or a plan of changes. enum: - question - blueprint - plan type: string origin: description: >- Who wrote this revision: the assistant, or the person through an inline edit. enum: - assistant - user type: string plan: $ref: '#/components/schemas/AssistantPlan' description: The changes, on a plan interaction. questions: description: The questions, on a question interaction. items: $ref: '#/components/schemas/AssistantQuestion' type: array requestedAt: description: When this revision was put in front of the reader. format: date-time type: string revision: description: >- Revision number, starting at 1. Only the latest revision of a pending interaction can be decided. minimum: 1 type: integer maximum: 9007199254740991 status: description: Lifecycle state of the interaction. enum: - pending - answered - accepted - revision_requested - cancelled - superseded - executing - completed - failed type: string stepResults: description: What each approved step did, once a plan executes. items: $ref: '#/components/schemas/AssistantPlanStepResult' type: array summary: description: One or two sentences on why this is being asked. type: string title: description: Short heading for the interaction. type: string required: - interactionId - kind - revision - digest - status - origin - title - requestedAt type: object additionalProperties: false StandaloneV2ContentBlock: properties: byteSize: description: Decoded image byte size. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 content: description: >- Nested blocks carrying a tool_result payload, so a tool can return both text and images. items: $ref: '#/components/schemas/StandaloneV2ContentBlock' type: array context: description: >- A document block's context: what the model should know about the document before reading it, disclosed as its first paragraph. type: string data: description: >- Base64 image bytes. Omitted from default reads and present only for legacy storage or explicit hydrate=images responses. type: string encryptedContent: description: >- Sealed reasoning payload for providers that return reasoning encrypted. Opaque to clients; replay it verbatim. type: string height: description: Validated image height in pixels. type: integer minimum: -9007199254740991 maximum: 9007199254740991 id: description: >- Provider-assigned id of a tool_use block. Echo it back as tool_use_id on the matching tool_result. type: string input: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Tool arguments the model produced for a tool_use block, matching that tool's input schema. type: object isError: description: >- True when a tool_result reports that the tool call failed; the nested content then carries the error detail. type: boolean mediaType: description: >- Declared media type; inline computer-use images allow image/jpeg, image/png, and image/webp. type: string name: description: Name of the tool the model is invoking, on a tool_use block. type: string omittedBytes: description: Original byte count reported by a redacted image placeholder. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 payload: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Provider-native block body, stored verbatim for block types this schema does not model. Passed through unchanged. provider: description: >- Provider that emitted a passthrough block, e.g. anthropic or openai, telling readers how to interpret payload. type: string providerPayload: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Original provider block exactly as received, kept alongside the normalized fields for lossless replay. redacted: description: >- True when the block's content was withheld (redacted thinking, or an image dropped by redaction); the remaining fields describe what was removed. type: boolean semanticHint: description: >- Coarse hint about what an unmodeled provider block represents, so a reader can render it without provider-specific logic. type: string sha256: description: Lowercase SHA-256 digest of decoded image bytes. type: string signature: description: >- Provider-issued signature over a thinking block, or the thought signature a Gemini tool_use block was issued with, required for the provider to accept that block on a later turn. Opaque; replay it verbatim. type: string source: $ref: '#/components/schemas/StandaloneV2ContentBlockSource' description: >- Where a user-sent image or document block's bytes came from when they were named rather than sent inline: {type: "file", file_id}. Kept on the stored block as provenance after the bytes were copied into the session; an image block then also carries the session's own uri. summary: description: >- Readable summary blocks a provider returns alongside sealed or long-form reasoning. items: $ref: '#/components/schemas/StandaloneV2ContentBlock' type: array text: description: Text of a text block, or the reasoning text of a thinking block. type: string title: description: >- A document block's title, disclosed to the model beside the document. type: string toolUseId: description: Id of the tool_use block that this tool_result answers. type: string type: description: >- Block discriminator: text, image, document (a user-sent block naming a file by id, inlined as text when the message is accepted), tool_use, tool_result, thinking, redacted_thinking, or a provider passthrough type. Which of the other fields apply depends on this value. type: string uri: description: >- Private typed content reference. Fetch it through managedAgentsGetSessionImage; clients cannot read this URI directly. type: string url: description: >- Short-lived HTTPS URL for the image bytes. Present only when the read asked for imageUrls=signed and the deployment has signing configured. Never stored; fetch a fresh read after urlExpiresAt. type: string urlExpiresAt: description: When url stops working. Absent whenever url is. format: date-time type: string width: description: Validated image width in pixels. type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - type type: object additionalProperties: false StandaloneV2EvaluationBudgetReached: properties: affectedTargetSessionIds: description: Target sessions stopped or not admitted because the cap was reached. items: type: string type: array maxTreeCostUsd: description: Exact decimal USD tree cap that stopped further admission. type: string required: - maxTreeCostUsd - affectedTargetSessionIds type: object additionalProperties: false StandaloneV2EvaluationPlanFrozen: properties: criteria: description: Ordered rubric criteria frozen from the evaluator version. items: $ref: '#/components/schemas/StandaloneV2EvaluationPlanCriterion' type: array maxConcurrentThreads: description: Maximum evaluation children admitted concurrently for this run. type: integer minimum: -9007199254740991 maximum: 9007199254740991 maxTreeCostUsd: description: >- Optional exact decimal USD cap on billed cost shared by the evaluation tree. type: string targets: description: Ordered target sessions and their immutable transcript snapshots. items: $ref: '#/components/schemas/StandaloneV2EvaluationPlanTarget' type: array required: - targets - criteria - maxConcurrentThreads type: object additionalProperties: false StandaloneV2EvaluationRunFinished: properties: failureCode: description: Stable systemic failure classification for a failed run. type: string failureMessage: description: Sanitized explanation of the systemic run failure. type: string targetsBudgetReached: description: >- Number of targets stopped or not admitted after the cost cap was reached. type: integer minimum: -9007199254740991 maximum: 9007199254740991 targetsSkipped: description: >- Number of targets whose processing ended without a completed verdict audit. type: integer minimum: -9007199254740991 maximum: 9007199254740991 targetsTotal: description: Number of target snapshots frozen in the plan. type: integer minimum: -9007199254740991 maximum: 9007199254740991 terminalStatus: description: Final lifecycle state of the evaluation run. type: string verdictsRecorded: description: Number of completed verdict audit events recorded for this run. type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - terminalStatus - targetsTotal - verdictsRecorded - targetsSkipped - targetsBudgetReached type: object additionalProperties: false StandaloneV2EvaluationTargetSkipped: properties: childSessionId: description: Evaluation child identity when creation reached that stage. format: uuid type: string reason: description: Sanitized operator-readable explanation of the skip. type: string reasonCode: description: Stable machine-readable classification of the skipped target. type: string snapshotEventId: description: Canonical transcript event boundary frozen for the skipped target. format: uuid type: string targetSessionId: description: >- Root target whose processing ended without a completed verdict audit. format: uuid type: string required: - targetSessionId - snapshotEventId - reasonCode - reason type: object additionalProperties: false StandaloneV2EvaluationTargetStarted: properties: childSessionId: description: Evaluation child session created for this target. format: uuid type: string cloneState: description: Whether the child received a ready clone or needed no sandbox. type: string evaluationId: description: Immutable verdict identity reserved for this target. format: uuid type: string sandboxProvider: description: Provider of the isolated clone when the target has a sandbox. type: string snapshotEventId: description: >- Canonical event id bounding the immutable target transcript snapshot. format: uuid type: string targetSessionId: description: Root session whose frozen snapshot is being evaluated. format: uuid type: string required: - targetSessionId - snapshotEventId - childSessionId - evaluationId - cloneState type: object additionalProperties: false StandaloneV2EvaluationVerdictRecorded: properties: childSessionId: description: Evaluation child session that produced the verdict. format: uuid type: string costCompleteness: description: Whether every cost component is final and priced. type: string costUsd: description: Exact canonical decimal USD attributed to this evaluation. type: string evaluationId: description: Immutable evaluation row that remains authoritative. format: uuid type: string failedCriterionKeys: description: Sorted unique rubric keys whose verdict is fail. items: type: string type: array result: description: Overall verdict derived from the frozen criterion results. type: string snapshotEventId: description: Canonical event id bounding the transcript evidence considered. format: uuid type: string targetSessionId: description: Root session evaluated by this immutable verdict. format: uuid type: string required: - targetSessionId - snapshotEventId - childSessionId - evaluationId - result - failedCriterionKeys - costUsd - costCompleteness type: object additionalProperties: false PlanItem: description: >- One step of a plan or to-do list an agent reported while working. Appears on an event's content when the agent's harness emits a plan; the service records it without acting on it. properties: content: description: Text of the planned step as the agent wrote it. type: string id: description: >- Identifier for this plan entry, stable across the turns that update it. type: string status: description: >- Progress value the agent reported for this step. Passed through as written and not interpreted by the service. type: string required: - id - content - status type: object additionalProperties: false StandaloneV2ToolDefinition: properties: description: description: >- Natural-language explanation of what the tool does and when to use it, supplied to the model verbatim. type: string inputSchema: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- JSON Schema for the tool's arguments. Passed to the model provider unchanged. type: - object - 'null' name: description: >- Tool name the model calls, matching the name on the resulting tool_use content block. type: string required: - name - description - inputSchema type: object additionalProperties: false StandaloneV2Usage: properties: cacheReadTokens: description: >- Prompt tokens served from the provider's prompt cache, billed at the cached rate. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 cacheWriteTokens: description: Prompt tokens written into the provider's prompt cache. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 costUsd: description: Accrued cost in USD, derived from cost_micros for display. format: double type: number inputTokens: description: Prompt tokens billed for this unit of work. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 outputTokens: description: Completion tokens billed for this unit of work. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 type: object additionalProperties: false AssistantBlueprint: description: >- A solution design for the reader's use case: what starts the work, the agents, the capabilities it uses and what it produces. properties: agents: description: The agents and the part each plays. items: $ref: '#/components/schemas/AssistantBlueprintAgent' type: array capabilities: description: >- Platform capabilities the design uses, each resolved against the capability catalog. items: $ref: '#/components/schemas/AssistantBlueprintCapability' type: array checkpoints: description: Where a person reviews or decides. items: type: string type: array costClass: description: Rough running cost. enum: - low - medium - high type: string environment: description: The environment the agents run in, in words. type: string evaluation: description: How success is judged. type: string gaps: description: What the platform cannot do directly, said plainly. items: type: string type: array outputs: description: What the work produces. items: type: string type: array trigger: $ref: '#/components/schemas/AssistantBlueprintTrigger' description: What starts the work. required: - trigger - agents - capabilities type: object additionalProperties: false AssistantDecision: description: The reader's decision on an interaction. properties: answers: description: Answers, on a question interaction. items: $ref: '#/components/schemas/AssistantQuestionAnswer' type: array comments: description: Comments pinned to steps or fields, with a revision request. items: $ref: '#/components/schemas/AssistantComment' type: array decidedAt: description: When the decision was recorded. format: date-time type: string decidedBy: description: The user who decided. type: string decision: description: >- What was decided. superseded_by_interaction means the assistant replaced the interaction with a different one before the reader decided. enum: - answered - accepted - approved - revision_requested - cancelled - superseded_by_interaction type: string note: description: The reader's note. type: string required: - decision - decidedAt type: object additionalProperties: false AssistantPlan: description: An ordered set of changes the reader approves, edits, or asks to revise. properties: prerequisites: description: >- Setup the plan cannot do itself; approval waits for each one the server can check. items: $ref: '#/components/schemas/AssistantPlanPrerequisite' type: array steps: description: Changes in execution order. items: $ref: '#/components/schemas/AssistantPlanStep' type: array required: - steps type: object additionalProperties: false AssistantQuestion: description: One typed question of a question interaction. properties: allowOther: description: Whether a select question also accepts a free-text answer. type: boolean input: description: How the question is answered. enum: - single_select - multi_select - short_text - long_text - confirm - picker type: string multiple: description: Whether a picker question accepts more than one resource. type: boolean optional: description: Whether the question may be left unanswered. type: boolean options: description: >- The choices of a select or picker question. Picker options are resolved by the server from resources the reader can access. items: $ref: '#/components/schemas/AssistantQuestionOption' type: array picker: description: Which kind of resource a picker question selects. enum: - agent - environment - skill - vault - model - agent_template - environment_template type: string prompt: description: The question. type: string questionId: description: Id of the question within the interaction. type: string required: - questionId - prompt - input type: object additionalProperties: false AssistantPlanStepResult: description: What one approved plan step did. properties: link: description: Console path to it. type: string message: description: Detail, or the error. type: string resourceId: description: The id of what it created or changed. type: string resourceKind: description: What it created or changed. type: string status: description: >- How it ended, or running while it runs. uncertain means the outcome could not be confirmed and the step was not retried. enum: - running - completed - failed - skipped - uncertain type: string stepId: description: The plan step this result is for. type: string required: - stepId - status type: object additionalProperties: false StandaloneV2ContentBlockSource: properties: fileId: description: >- The file whose bytes the block carries, from the caller's organization, unexpired. type: string type: description: Always file. enum: - file type: string required: - type - fileId type: object additionalProperties: false StandaloneV2EvaluationPlanCriterion: properties: criterionKey: description: Stable rubric key used to join verdicts across the run. type: string criterionText: description: Frozen rubric instruction evaluated for every target. type: string required: - criterionKey - criterionText type: object additionalProperties: false StandaloneV2EvaluationPlanTarget: properties: snapshotEventId: description: >- Canonical event id at or before which the target transcript is frozen. format: uuid type: string targetSessionId: description: Root session selected as an immutable evaluation target. format: uuid type: string required: - targetSessionId - snapshotEventId type: object additionalProperties: false AssistantBlueprintAgent: description: One agent of a blueprint and the part it plays. properties: model: description: The model it runs on, when chosen. type: string responsibilities: description: What it does. type: string role: description: The agent's role. type: string required: - role type: object additionalProperties: false AssistantBlueprintCapability: description: >- One platform capability a blueprint uses, resolved against the capability catalog. properties: capabilityId: description: Id from the capability catalog. type: string kind: description: Capability kind, resolved by the server. type: string name: description: Customer-facing name, resolved by the server. type: string purpose: description: Why the design uses it. type: string status: description: Its status in this organization, resolved by the server. type: string required: - capabilityId - name - kind - status type: object additionalProperties: false AssistantBlueprintTrigger: description: What starts the work a blueprint describes. properties: detail: description: The schedule or the event, in words. type: string kind: description: Manual, on a schedule, or on an outside event. enum: - manual - schedule - event type: string required: - kind type: object additionalProperties: false AssistantQuestionAnswer: description: The reader's answer to one question. properties: optionIds: description: >- Selected option ids, for select, picker and confirm questions (confirm answers with yes or no). items: type: string type: array questionId: description: The question answered. type: string text: description: Free text, for text questions or an Other answer. maxLength: 4000 type: string required: - questionId type: object additionalProperties: false AssistantComment: description: A comment pinned to a step or field of a blueprint or plan. properties: field: description: The field commented on. type: string stepId: description: The step commented on. type: string text: description: The comment. maxLength: 2000 type: string required: - text type: object additionalProperties: false AssistantPlanPrerequisite: description: >- Setup a plan cannot do itself; approval waits for it when the server can check it. properties: capabilityId: description: The capability it unlocks. type: string detail: description: Why, and anything to choose while doing it. type: string kind: description: >- What the reader has to do. The server checks connect_integration and needs_admin when they name a capability; add_vault_credential is a reminder it cannot check. enum: - connect_integration - add_vault_credential - needs_admin type: string label: description: What to do, in words. type: string link: description: Console path that starts the setup. type: string prerequisiteId: description: Id within the plan. type: string satisfied: description: >- Whether the server found it done when this revision was written; false for a prerequisite it cannot check. type: boolean required: - prerequisiteId - kind - label - satisfied type: object additionalProperties: false AssistantPlanStep: description: >- One change of a plan: an action and the exact request it runs on approval. properties: action: description: The action, from the closed set the assistant can propose. type: string costClass: description: Whether approving the step can spend credit. enum: - none - model_spend type: string dependsOn: description: Earlier steps whose results this step uses. items: type: string type: array enabled: description: Whether the step runs on approval. type: boolean fields: description: How to render the step's input as a form. items: $ref: '#/components/schemas/AssistantPlanField' type: array input: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- The action's request, as the server validated and normalized it. A value {"$ref": "steps.."} is filled from an earlier step's result. type: - object - 'null' optional: description: Whether the reader may turn the step off. type: boolean stepId: description: >- Id of the step within the plan; later steps refer to its outputs by it. type: string title: description: What the step does, in words. type: string warnings: description: Things the reader should know before approving. items: type: string type: array required: - stepId - action - title - enabled - input - costClass type: object additionalProperties: false AssistantQuestionOption: description: One choice of a select or picker question, or of a plan field. properties: description: description: Optional detail shown under the label. type: string label: description: What the reader sees. type: string optionId: description: Id to answer with. type: string required: - optionId - label type: object additionalProperties: false AssistantPlanField: description: How a console renders one field of a plan step's input. properties: help: description: Short guidance shown with the field. type: string label: description: Field label. type: string name: description: Top-level key in the step input. type: string options: description: Choices for select and picker widgets, resolved by the server. items: $ref: '#/components/schemas/AssistantQuestionOption' type: array required: description: Whether the field must have a value. type: boolean widget: description: The control to render. enum: - text - long_text - markdown - code - select - multi_select - model_picker - environment_picker - agent_picker - skill_picker - vault_reference - key_list - number - boolean - resources - json type: string required: - name - label - widget type: object additionalProperties: false headers: RecursionOrganizationId: description: Organization id resolved for this request. schema: minLength: 1 type: string RecursionTenantId: description: Tenant id resolved for this request. schema: minLength: 1 type: string securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````