> ## 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 timeline events > Returns one page of the root timeline's events in chronological order, plus next_page_token to continue from. A page can come back shorter than limit because an aggregate serialized-byte budget applies as well as the count, so treat an empty page with no token as the end rather than inferring the end from the length. Large event payloads hydrate by default; pass payloads=refs for bounded stubs instead. ## OpenAPI ````yaml /recursion/openapi.yaml get /managed-agents/v1/sessions/{sessionId}/events 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/{sessionId}/events: get: tags: - Sessions summary: Get root timeline events description: >- Returns one page of the root timeline's events in chronological order, plus next_page_token to continue from. A page can come back shorter than limit because an aggregate serialized-byte budget applies as well as the count, so treat an empty page with no token as the end rather than inferring the end from the length. Large event payloads hydrate by default; pass payloads=refs for bounded stubs instead. operationId: managedAgentsListSessionEvents parameters: - description: >- Exclusive continuation cursor: a lowercase canonical UUID event id, normally the previous page's next_page_token. Malformed values return 400. in: query name: after_event_id schema: description: >- Exclusive continuation cursor: a lowercase canonical UUID event id, normally the previous page's next_page_token. Malformed values return 400. type: string - description: >- Maximum event count requested. The response may contain fewer events when the aggregate serialized-byte budget is reached. in: query name: limit schema: default: 100 description: >- Maximum event count requested. The response may contain fewer events when the aggregate serialized-byte budget is reached. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - 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 - 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: image_urls 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 - 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 - description: Session id (UUID) whose root timeline is read. in: path name: sessionId required: true schema: description: Session id (UUID) whose root timeline is read. format: uuid type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' responses: '200': content: application/json: schema: $ref: '#/components/schemas/EventPageResponse' description: >- Response body of GET /managed-agents/v1/sessions/{sessionId}/events: one page of the merged chronological timeline for the whole session tree the path session belongs to, not just that session's own events. The page is bounded twice, by the limit parameter and by an aggregate serialized-byte budget, and the byte budget wins; a single event too large for the budget is returned alone with its content marked oversized and must be fetched in full from the per-event content endpoint. 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: type: string minLength: 1 RecursionOrganizationId: name: x-organization-id in: header required: false description: >- Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or `default`. schema: type: string minLength: 1 schemas: EventPageResponse: description: >- Response body of GET /managed-agents/v1/sessions/{sessionId}/events: one page of the merged chronological timeline for the whole session tree the path session belongs to, not just that session's own events. The page is bounded twice, by the limit parameter and by an aggregate serialized-byte budget, and the byte budget wins; a single event too large for the budget is returned alone with its content marked oversized and must be fetched in full from the per-event content endpoint. properties: events: description: >- One chronological page of the root timeline, oldest first. Null rather than an empty array when no event follows the requested watermark, which is the normal answer when a caller has already read to the end. items: $ref: '#/components/schemas/Event' type: - array - 'null' next_page_token: description: >- Watermark to continue from: pass it back as the after_event_id query parameter to fetch the next page. Its value is the event_id of the last event in this page. Always present, and an empty string means this page reached the end of the timeline as of this read. Because the page can be cut short by a byte budget before the requested limit is reached, a short events array with a non-empty token means more remain, not that the timeline ended. type: string required: - events - next_page_token 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. Event: description: >- One durable entry in a session's transcript: a message, a tool call or result, an approval, or a status change, with the provider message body and the token accounting for the call that produced it. Returned when listing or streaming a session's events. 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 agent_id: description: Agent that produced this event (UUID). type: string cache_read_tokens: description: >- Prompt tokens served from the provider's prompt cache, billed at the cached rate. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 cache_write_tokens: description: Prompt tokens written into the provider's prompt cache. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 causal_event_id: description: >- Event that caused this one (UUID). Unlike parent_event_id this expresses causality rather than nesting. type: string content: $ref: '#/components/schemas/EventContent' description: >- The event payload as provider-shaped content blocks. Passed through to and from the model provider without reinterpretation. content_hydration_status: description: >- Read-time status when external EventContent was hydrated or could not be hydrated. enum: - hydrated - refs_only - missing - corrupt - unavailable - oversized type: string content_payload_bytes: description: Byte size of the canonical external EventContent JSON. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 content_payload_ref: description: >- Private whole-event content reference. Read the content through managedAgentsGetSessionEventContent; this reference cannot be fetched directly. type: string content_payload_sha256: description: >- Lowercase SHA-256 digest of the canonical external EventContent JSON. type: string content_ref: description: >- Image cleanup prefix or typed multi-image envelope. This is independent of whole-event payload storage. type: string cost_micros: 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 created_at: description: RFC 3339 timestamp of when this record was created. Server-assigned. format: date-time type: string environment_id: description: Sandbox environment the producing session was executing in (UUID). type: string event_id: 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 event_status: description: >- Outcome marker for events that can fail: pending, completed, warning, or error. Empty when not applicable. type: string event_type: 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, or outcome_evaluation. type: string finish_reason: description: >- Why the provider stopped generating, in the provider vocabulary (for example end_turn, max_tokens, tool_use). Passed through verbatim. type: string inference_config: $ref: '#/components/schemas/InferenceConfig' description: >- Sampling and tool settings this inference ran with, as resolved at call time. input_tokens: description: Prompt tokens billed for this unit of work. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 latency_ms: description: Wall-clock duration of the provider call in milliseconds. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 model: $ref: '#/components/schemas/ModelRef' description: >- Snapshot of the model reference as it was at call time, so a later model change does not rewrite history. model_ref_id: description: >- Canonical model reference used for this inference (UUID). Empty on events not produced by a model call. type: string organization_id: description: >- Organization that owns this record. Resolved from the API key; never accepted from the caller. type: string output_tokens: description: Completion tokens billed for this unit of work. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 parent_event_id: description: >- Event this one is nested under in the transcript tree (UUID), for example a tool result under its invocation. type: string prompt_tokens: 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 provider_model_id: description: >- Provider's own model identifier as sent on the wire, which may differ from the canonical model reference. type: string provider_request_id: description: >- Provider's request identifier for this inference, for correlating with provider-side logs. type: string provider_type: 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 sandbox_instance_id: description: >- Concrete sandbox instance the event was produced on. Provider-assigned, not a UUID. type: string schema_version: description: >- Event schema version this row was written under. Server-assigned; readers should tolerate unknown newer values. type: integer minimum: -9007199254740991 maximum: 9007199254740991 session_id: description: Session this event belongs to (UUID). type: string thread_id: description: >- Thread within a multi-agent session that produced this event (UUID). Empty on a single-agent session. type: string tool_name: description: >- Name of the tool being invoked or reporting a result. Set on tool events only. type: string tool_use_id: description: >- Provider's tool-call identifier, correlating a tool_invocation with its tool_result. type: string turn_id: description: Groups every event produced within one model turn. type: string required: - schema_version - event_type - actor - content - inference_config - session_id - event_id - created_at 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. EventContent: description: >- The body of a session event, shaped like a provider message: content blocks plus the stop reason and token usage the provider returned. Every event in a session transcript carries one. 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/ContentBlock' type: - array - 'null' 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 stop_reason: 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/ToolDefinition' type: array usage: $ref: '#/components/schemas/Usage' 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 InferenceConfig: description: >- Sampling and generation settings for a model call, mirroring the provider's own request parameters. Set it on an agent or a session to govern every turn, and read it back on a model event to see what the call actually used. properties: max_tokens: 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 provider_params: 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 reasoning_effort: 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 top_p: 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 ModelRef: description: >- Snapshot of the model that served one inference call, recorded on the event so a transcript stays interpretable after the catalog entry changes. Returned on model events; also accepted when pinning a session to a specific model. properties: base_url: 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 context_window: 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 max_output_tokens: 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 model_ref_id: 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 model_version: 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 provider_id: description: >- Model provider record whose credentials and base URL were used (UUID). type: string provider_type: description: >- Provider family that served the call, e.g. anthropic, openai, vertex, or mock. Selects which wire protocol the request used. type: string serving_backend: 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 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 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 ContentBlock: description: >- One block of message content: text, image, tool_use, tool_result, thinking, or a provider passthrough. The type field says which fields apply, and provider-native payloads are carried through verbatim. properties: byte_size: 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/ContentBlock' 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 encrypted_content: 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 is_error: description: >- True when a tool_result reports that the tool call failed; the nested content then carries the error detail. type: boolean media_type: 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 omitted_bytes: 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 provider_payload: $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 semantic_hint: 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/ContentBlockSource' 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/ContentBlock' 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 tool_use_id: 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 image_urls=signed and the deployment has signing configured. Never stored; fetch a fresh read after url_expires_at. type: string url_expires_at: 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 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 ToolDefinition: description: >- One tool as it was offered to the model, in the Anthropic and OpenAI tool-definition vocabulary. Recorded on the event for a model turn so a reader can see exactly what the model could call. properties: description: description: >- Natural-language explanation of what the tool does and when to use it, supplied to the model verbatim. type: string input_schema: 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 - input_schema type: object additionalProperties: false Usage: description: >- Token counts and cost for a single unit of work, in the provider's usage vocabulary. Attached to an event's content for the model turn that produced it; see session usage for whole-session totals. properties: cache_read_tokens: description: >- Prompt tokens served from the provider's prompt cache, billed at the cached rate. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 cache_write_tokens: description: Prompt tokens written into the provider's prompt cache. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 cost_usd: description: Accrued cost in USD, derived from cost_micros for display. format: double type: number input_tokens: description: Prompt tokens billed for this unit of work. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 output_tokens: 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 ContentBlockSource: description: >- Where a user-sent image or document block takes its bytes from when the caller names a file instead of carrying them: a file from the organization's catalog, read and copied into the session when the message is accepted, so the block the transcript keeps names both the source and the copy. properties: file_id: type: string minLength: 1 description: Nonempty id of an unexpired file in the caller's organization. type: type: string const: file description: Always file. required: - type - file_id 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: type: string minLength: 1 RecursionTenantId: description: Tenant id resolved for this request. schema: type: string minLength: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````