> ## 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 /managed-agents/openapi.yaml get /managed-agents/v1/sessions/{session_id}/events openapi: 3.1.0 info: title: Managed Agents API version: 0.13.0 description: >- The Recursion Managed Agents REST API. Authenticate with a Recursion API key as a bearer token. An organization-scoped key acts in its own organization and needs nothing else; a tenant-scoped key must also send `x-organization-id` with an organization id or `default`. Field names follow each operation's published schema. servers: - url: https://api.recursion.labelbox.com security: - bearerAuth: [] paths: /managed-agents/v1/sessions/{session_id}/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 - 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 getSessionImage 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 getSessionImage 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: session_id required: true schema: description: Session id (UUID) whose root timeline is read. format: uuid type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsEventPageResponse' description: >- Response body of GET /v1/sessions/{session_id}/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. '400': description: The request was rejected by schema or semantic validation. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '401': description: The caller is unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '403': description: The caller lacks a required permission or capability. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' '404': description: No such resource is reachable for this caller. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '429': headers: Retry-After: description: Seconds the caller should wait before retrying. schema: type: string style: simple description: A rate limit is exhausted. Honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '500': description: An unexpected server-side failure. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '502': description: The service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorBadGateway' '503': headers: Retry-After: description: Seconds the caller should wait before retrying. schema: type: string style: simple description: A dependency is unavailable. Retryable. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string description: The service did not respond before the timeout. Retryable. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorGatewayTimeout' components: schemas: ManagedAgentsEventPageResponse: description: >- Response body of GET /v1/sessions/{session_id}/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/ManagedAgentsEvent' 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 example: events: - actor: human:api agent_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d cache_read_tokens: 1 cache_write_tokens: 1 causal_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d content: blocks: - byte_size: 1 content: [] context: example data: example encrypted_content: example height: 1 id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d input: key: example is_error: true media_type: example name: example-name omitted_bytes: 1 payload: example provider: example provider_payload: example redacted: true semantic_hint: example sha256: example signature: example source: file_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: file summary: [] text: example title: example tool_use_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: example uri: example url: https://example.com url_expires_at: '2026-02-18T09:30:00.000Z' width: 1 evaluation_budget_reached: affected_target_session_ids: - 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d max_tree_cost_usd: example evaluation_plan_frozen: criteria: - criterion_key: example criterion_text: example max_concurrent_threads: 1 max_tree_cost_usd: example targets: - snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d evaluation_run_finished: failure_code: plan_failed failure_message: example targets_budget_reached: 1 targets_skipped: 1 targets_total: 1 terminal_status: completed verdicts_recorded: 1 evaluation_target_skipped: child_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d reason: example reason_code: child_create_failed snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d evaluation_target_started: child_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d clone_state: ready evaluation_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sandbox_provider: example snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d evaluation_verdict_recorded: child_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d cost_completeness: complete cost_usd: example evaluation_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d failed_criterion_keys: - example result: pass snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d metadata: key: example plan: - content: example id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d status: example stop_reason: example tools: - description: example input_schema: key: example name: example-name usage: cache_read_tokens: 1 cache_write_tokens: 1 cost_usd: 1.5 input_tokens: 1 output_tokens: 1 content_hydration_status: hydrated content_payload_bytes: 1 content_payload_ref: example content_payload_sha256: example content_ref: example cost_micros: 1 created_at: '2026-02-18T09:30:00.000Z' environment_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d event_status: example event_type: example finish_reason: example inference_config: max_tokens: 1 provider_params: key: example reasoning_effort: example temperature: 1.5 top_p: 1.5 input_tokens: 1 latency_ms: 1 model: base_url: https://example.com capabilities: key: example context_window: 1 max_output_tokens: 1 metadata: key: example model: example model_ref_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d model_version: example provider: example provider_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d provider_type: example serving_backend: example model_ref_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d organization_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d output_tokens: 1 parent_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d prompt_tokens: 1 provider_model_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d provider_request_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d provider_type: example role: user sandbox_instance_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d schema_version: 1 session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d thread_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d tool_name: example tool_use_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d turn_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d next_page_token: example ManagedAgentsApiError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - analytics - analytics_not_ready - artifact_fetch_unavailable - artifact_generation_mismatch - artifact_hash_mismatch - artifact_invalid_events - artifact_invalid_json - artifact_not_allowlisted - artifact_size_mismatch - atomic_ingest_timeout - auth_unavailable - automation_event_source_invalid - automation_memory_unavailable - automation_reference_invalid - automation_runs_unconfigured - automations_unconfigured - bad_gateway - built_in_catalog_unavailable - built_in_integrations_unconfigured - compute_offerings_unavailable - conflict - content_store_request_canceled - content_store_unavailable - content_store_upload_timeout - credential_encryption_unconfigured - delegate_preparation_failed - entity_family_not_permitted - environment_not_verified - evaluation_cancellation_pending - evaluation_deletion_pending - event_admission_unavailable - event_ingress_unavailable - event_source_verification_credential_invalid - event_sources_unconfigured - execution_unconfigured - file_quota_exceeded - file_storage_unconfigured - forbidden - gateway_timeout - gestalt_unconfigured - github_rate_limited - github_unavailable - handoff_access_invalid - handoff_access_unavailable - handoff_access_unsupported - handoff_capture_unavailable - handoff_requires_retest - handoff_revoke_unavailable - handoff_signal_unavailable - idempotency_conflict - idempotency_in_progress - idempotency_unavailable - ingest_policy_changed - ingest_policy_not_found - ingest_policy_revoked - integrations_unconfigured - internal_error - invalid_json - invalid_pull_request_review_result - invalid_request - invalid_scope - invariant_violation - live_fleet_unconfigured - managed_agents_unavailable - missing_dependency - model_gateway_metadata_missing - model_gateway_unconfigured - model_gateway_unreachable - mutation_transaction_budget_exceeded - not_found - page_token_expired - payload_too_large - persistence_busy - precondition_failed - precondition_required - provider_registration_unsupported - provider_selection_unsupported - rate_limit_exceeded - rate_limited - repository_automation_unconfigured - request_too_large - reserved_source_type - revision_conflict - run_log_store_unavailable - runner_image_resolution_failed - sandbox_provider_disabled - service_unavailable - session_analyst_busy - session_analyst_model_unavailable - session_analyst_unconfigured - session_start_admission_unavailable - session_start_not_admitted - setup_fallback_environment_unsafe - setup_run_finished - setup_run_in_progress - setup_run_limit - setup_run_not_started - setup_runs_unavailable - skill_storage_unconfigured - slack_channels_rejected - slack_channels_unavailable - slack_channels_unconfigured - slack_connection_malformed - slack_event_intake_unavailable - slack_installation_mismatch - slack_missing_scope - slack_rate_limited - slack_reapproval_required - source_ownership_mismatch - source_revision_conflict - spanner_unavailable - streaming_unsupported - submission_transaction_budget_exceeded - task_version_number_conflict - team_board_unconfigured - too_many_streams - unauthorized - unsupported_media_type - vault_creation_retired - version_content_conflict - webhook_delivery_too_large - workspace_boundary_denied message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorForbidden: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - forbidden message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorBadGateway: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorGatewayTimeout: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - gateway_timeout message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsEvent: 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 cache_write_tokens: description: Prompt tokens written into the provider's prompt cache. format: int64 type: integer 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/ManagedAgentsEventContent' 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 content_payload_ref: description: >- Private whole-event content reference. Read the content through getSessionEventContent; 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 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/ManagedAgentsInferenceConfig' 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 latency_ms: description: Wall-clock duration of the provider call in milliseconds. format: int64 type: integer model: $ref: '#/components/schemas/ManagedAgentsModelRef' 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 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 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 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 example: actor: human:api agent_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d cache_read_tokens: 1 cache_write_tokens: 1 causal_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d content: blocks: - byte_size: 1 content: [] context: example data: example encrypted_content: example height: 1 id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d input: key: example is_error: true media_type: example name: example-name omitted_bytes: 1 payload: example provider: example provider_payload: example redacted: true semantic_hint: example sha256: example signature: example source: file_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: file summary: [] text: example title: example tool_use_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: example uri: example url: https://example.com url_expires_at: '2026-02-18T09:30:00.000Z' width: 1 evaluation_budget_reached: affected_target_session_ids: - 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d max_tree_cost_usd: example evaluation_plan_frozen: criteria: - criterion_key: example criterion_text: example max_concurrent_threads: 1 max_tree_cost_usd: example targets: - snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d evaluation_run_finished: failure_code: plan_failed failure_message: example targets_budget_reached: 1 targets_skipped: 1 targets_total: 1 terminal_status: completed verdicts_recorded: 1 evaluation_target_skipped: child_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d reason: example reason_code: child_create_failed snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d evaluation_target_started: child_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d clone_state: ready evaluation_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sandbox_provider: example snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d evaluation_verdict_recorded: child_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d cost_completeness: complete cost_usd: example evaluation_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d failed_criterion_keys: - example result: pass snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d metadata: key: example plan: - content: example id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d status: example stop_reason: example tools: - description: example input_schema: key: example name: example-name usage: cache_read_tokens: 1 cache_write_tokens: 1 cost_usd: 1.5 input_tokens: 1 output_tokens: 1 content_hydration_status: hydrated content_payload_bytes: 1 content_payload_ref: example content_payload_sha256: example content_ref: example cost_micros: 1 created_at: '2026-02-18T09:30:00.000Z' environment_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d event_status: example event_type: example finish_reason: example inference_config: max_tokens: 1 provider_params: key: example reasoning_effort: example temperature: 1.5 top_p: 1.5 input_tokens: 1 latency_ms: 1 model: base_url: https://example.com capabilities: key: example context_window: 1 max_output_tokens: 1 metadata: key: example model: example model_ref_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d model_version: example provider: example provider_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d provider_type: example serving_backend: example model_ref_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d organization_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d output_tokens: 1 parent_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d prompt_tokens: 1 provider_model_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d provider_request_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d provider_type: example role: user sandbox_instance_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d schema_version: 1 session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d thread_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d tool_name: example tool_use_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d turn_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d ManagedAgentsEventContent: 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: 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/ManagedAgentsContentBlock' type: - array - 'null' evaluation_budget_reached: $ref: '#/components/schemas/ManagedAgentsEvaluationBudgetReached' description: >- Cost cap and targets stopped or left unadmitted when the run reached it. evaluation_plan_frozen: $ref: '#/components/schemas/ManagedAgentsEvaluationPlanFrozen' description: >- Frozen target, rubric, concurrency, and cost plan for an evaluation run. evaluation_run_finished: $ref: '#/components/schemas/ManagedAgentsEvaluationRunFinished' description: Terminal counts and systemic failure state for the evaluation run. evaluation_target_skipped: $ref: '#/components/schemas/ManagedAgentsEvaluationTargetSkipped' description: >- Sanitized outcome for a target whose processing ended without a completed verdict audit. evaluation_target_started: $ref: '#/components/schemas/ManagedAgentsEvaluationTargetStarted' description: Identity and clone state for one admitted evaluation target. evaluation_verdict_recorded: $ref: '#/components/schemas/ManagedAgentsEvaluationVerdictRecorded' description: Audit reference to one authoritative immutable evaluation verdict. metadata: additionalProperties: {} 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/ManagedAgentsPlanItem' 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/ManagedAgentsToolDefinition' type: array usage: $ref: '#/components/schemas/ManagedAgentsUsage' 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 example: blocks: - byte_size: 1 content: [] context: example data: example encrypted_content: example height: 1 id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d input: key: example is_error: true media_type: example name: example-name omitted_bytes: 1 payload: example provider: example provider_payload: example redacted: true semantic_hint: example sha256: example signature: example source: file_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: file summary: [] text: example title: example tool_use_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: example uri: example url: https://example.com url_expires_at: '2026-02-18T09:30:00.000Z' width: 1 evaluation_budget_reached: affected_target_session_ids: - 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d max_tree_cost_usd: example evaluation_plan_frozen: criteria: - criterion_key: example criterion_text: example max_concurrent_threads: 1 max_tree_cost_usd: example targets: - snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d evaluation_run_finished: failure_code: plan_failed failure_message: example targets_budget_reached: 1 targets_skipped: 1 targets_total: 1 terminal_status: completed verdicts_recorded: 1 evaluation_target_skipped: child_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d reason: example reason_code: child_create_failed snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d evaluation_target_started: child_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d clone_state: ready evaluation_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sandbox_provider: example snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d evaluation_verdict_recorded: child_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d cost_completeness: complete cost_usd: example evaluation_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d failed_criterion_keys: - example result: pass snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d metadata: key: example plan: - content: example id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d status: example stop_reason: example tools: - description: example input_schema: key: example name: example-name usage: cache_read_tokens: 1 cache_write_tokens: 1 cost_usd: 1.5 input_tokens: 1 output_tokens: 1 ManagedAgentsInferenceConfig: 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 provider_params: additionalProperties: {} description: >- Extra provider request parameters merged into the inference call for options this schema does not model. Keys are provider-specific and are passed through unvalidated. 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 example: max_tokens: 1 provider_params: key: example reasoning_effort: example temperature: 1.5 top_p: 1.5 ManagedAgentsModelRef: 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: {} 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 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 metadata: additionalProperties: {} 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. claude-sonnet-4-5 or anthropic/claude-sonnet-4-5. 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 example: base_url: https://example.com capabilities: key: example context_window: 1 max_output_tokens: 1 metadata: key: example model: example model_ref_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d model_version: example provider: example provider_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d provider_type: example serving_backend: example ManagedAgentsContentBlock: 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 content: description: >- Nested blocks carrying a tool_result payload, so a tool can return both text and images. items: $ref: '#/components/schemas/ManagedAgentsContentBlock' 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 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: {} 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 payload: 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: 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/ManagedAgentsContentBlockSource' 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/ManagedAgentsContentBlock' 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 getSessionImage; 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 required: - type type: object example: byte_size: 1 content: [] context: example data: example encrypted_content: example height: 1 id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d input: key: example is_error: true media_type: example name: example-name omitted_bytes: 1 payload: example provider: example provider_payload: example redacted: true semantic_hint: example sha256: example signature: example source: file_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: file summary: [] text: example title: example tool_use_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: example uri: example url: https://example.com url_expires_at: '2026-02-18T09:30:00.000Z' width: 1 ManagedAgentsEvaluationBudgetReached: additionalProperties: false description: >- Audit event payload listing targets stopped or left unadmitted when the evaluation tree reached its exact USD cap. properties: affected_target_session_ids: description: Target sessions stopped or not admitted because the cap was reached. items: format: uuid type: string minItems: 1 type: array max_tree_cost_usd: description: Exact decimal USD tree cap that stopped further admission. type: string required: - max_tree_cost_usd - affected_target_session_ids type: object example: affected_target_session_ids: - 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d max_tree_cost_usd: example ManagedAgentsEvaluationPlanFrozen: additionalProperties: false description: >- Audit event payload that freezes the complete target set, rubric, concurrency, and cost cap before child work starts. properties: criteria: description: Ordered rubric criteria frozen from the evaluator version. items: $ref: '#/components/schemas/ManagedAgentsEvaluationPlanCriterion' type: array max_concurrent_threads: description: Maximum evaluation children admitted concurrently for this run. minimum: 1 type: integer max_tree_cost_usd: 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/ManagedAgentsEvaluationPlanTarget' type: array required: - targets - criteria - max_concurrent_threads type: object example: criteria: - criterion_key: example criterion_text: example max_concurrent_threads: 1 max_tree_cost_usd: example targets: - snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d ManagedAgentsEvaluationRunFinished: additionalProperties: false description: >- Terminal audit payload summarizing planned targets, completed verdict audits, skips, budget stops, and any systemic failure. properties: failure_code: description: Stable systemic failure classification for a failed run. enum: - plan_failed - cleanup_failed - accounting_failed - audit_failed - finalization_failed type: string failure_message: description: Sanitized explanation of the systemic run failure. type: string targets_budget_reached: description: >- Number of targets stopped or not admitted after the cost cap was reached. minimum: 0 type: integer targets_skipped: description: >- Number of targets whose processing ended without a completed verdict audit. minimum: 0 type: integer targets_total: description: Number of target snapshots frozen in the plan. minimum: 0 type: integer terminal_status: description: Final lifecycle state of the evaluation run. enum: - completed - failed - cancelled type: string verdicts_recorded: description: Number of completed verdict audit events recorded for this run. minimum: 0 type: integer required: - terminal_status - targets_total - verdicts_recorded - targets_skipped - targets_budget_reached type: object example: failure_code: plan_failed failure_message: example targets_budget_reached: 1 targets_skipped: 1 targets_total: 1 terminal_status: completed verdicts_recorded: 1 ManagedAgentsEvaluationTargetSkipped: additionalProperties: false description: >- Audit event payload for a target whose processing ended without a completed verdict audit. properties: child_session_id: description: Evaluation child identity when creation reached that stage. format: uuid type: string reason: description: Sanitized operator-readable explanation of the skip. type: string reason_code: description: Stable machine-readable classification of the skipped target. enum: - child_create_failed - child_run_failed - verdict_invalid - cleanup_or_accounting_failed type: string snapshot_event_id: description: Canonical transcript event boundary frozen for the skipped target. format: uuid type: string target_session_id: description: >- Root target whose processing ended without a completed verdict audit. format: uuid type: string required: - target_session_id - snapshot_event_id - reason_code - reason type: object example: child_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d reason: example reason_code: child_create_failed snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d ManagedAgentsEvaluationTargetStarted: additionalProperties: false description: >- Audit event payload linking one frozen target to its isolated evaluation child and reserved verdict identity. properties: child_session_id: description: Evaluation child session created for this target. format: uuid type: string clone_state: description: Whether the child received a ready clone or needed no sandbox. enum: - ready - sandboxless type: string evaluation_id: description: Immutable verdict identity reserved for this target. format: uuid type: string sandbox_provider: description: Provider of the isolated clone when the target has a sandbox. type: string snapshot_event_id: description: >- Canonical event id bounding the immutable target transcript snapshot. format: uuid type: string target_session_id: description: Root session whose frozen snapshot is being evaluated. format: uuid type: string required: - target_session_id - snapshot_event_id - child_session_id - evaluation_id - clone_state type: object example: child_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d clone_state: ready evaluation_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sandbox_provider: example snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d ManagedAgentsEvaluationVerdictRecorded: additionalProperties: false description: >- Audit event payload emitted after the authoritative immutable verdict and clone cost are recorded. properties: child_session_id: description: Evaluation child session that produced the verdict. format: uuid type: string cost_completeness: description: Whether every cost component is final and priced. enum: - complete - pending - unpriced - partial - legacy_partial - indeterminate type: string cost_usd: description: Exact canonical decimal USD attributed to this evaluation. type: string evaluation_id: description: Immutable evaluation row that remains authoritative. format: uuid type: string failed_criterion_keys: description: Sorted unique rubric keys whose verdict is fail. items: type: string type: array uniqueItems: true result: description: Overall verdict derived from the frozen criterion results. enum: - pass - fail - not_applicable type: string snapshot_event_id: description: Canonical event id bounding the transcript evidence considered. format: uuid type: string target_session_id: description: Root session evaluated by this immutable verdict. format: uuid type: string required: - target_session_id - snapshot_event_id - child_session_id - evaluation_id - result - failed_criterion_keys - cost_usd - cost_completeness type: object example: child_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d cost_completeness: complete cost_usd: example evaluation_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d failed_criterion_keys: - example result: pass snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d ManagedAgentsPlanItem: 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 example: content: example id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d status: example ManagedAgentsToolDefinition: 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: {} 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 example: description: example input_schema: key: example name: example-name ManagedAgentsUsage: 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 cache_write_tokens: description: Prompt tokens written into the provider's prompt cache. format: int64 type: integer 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 output_tokens: description: Completion tokens billed for this unit of work. format: int64 type: integer type: object example: cache_read_tokens: 1 cache_write_tokens: 1 cost_usd: 1.5 input_tokens: 1 output_tokens: 1 ManagedAgentsContentBlockSource: 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: 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 - file_id type: object example: file_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: file ManagedAgentsEvaluationPlanCriterion: additionalProperties: false description: >- One stable rubric criterion frozen from the evaluator version for the complete run. properties: criterion_key: description: Stable rubric key used to join verdicts across the run. type: string criterion_text: description: Frozen rubric instruction evaluated for every target. type: string required: - criterion_key - criterion_text type: object example: criterion_key: example criterion_text: example ManagedAgentsEvaluationPlanTarget: additionalProperties: false description: >- One root target and the immutable transcript boundary frozen into an evaluation plan. properties: snapshot_event_id: description: >- Canonical event id at or before which the target transcript is frozen. format: uuid type: string target_session_id: description: Root session selected as an immutable evaluation target. format: uuid type: string required: - target_session_id - snapshot_event_id type: object example: snapshot_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d target_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````