Session data structures

Session object

Returned by create, get, list, update, and archive endpoints.

Field	Type	Description
`id`	string	Session ID with the `sess_` prefix
`type`	string	Always `"session"`
`agent`	object	Agent snapshot used by this Session. See Session embedded agent for the field shape
`environment_id`	string	Environment ID used by this Session
`status`	string	Session lifecycle status: `rescheduling`, `running`, `idle`, `canceling`, or `terminated`. `canceling` is a transient state returned by the Cancel endpoint acknowledgement; poll the Session or listen for status events to observe the final state
`title`	string \| null	Session title
`metadata`	object	Session metadata
`environment_variables`	object	Session-level environment variables exported into the agent runtime, returned as a JSON object (`{"NAME":"value"}`). Empty Sessions return `{}`. The request format is a single string (see Create a Session)
`incremental_streaming_enabled`	boolean	Whether this Session exposes incremental streaming events. Defaults to `false` when omitted at creation
`resources`	array of Session resource	File, GitHub repository, or Memory Store resources attached to the Session
`vault_ids`	array of string	Vault IDs attached to the Session
`deployment_id`	string \| null	Deployment ID when the Session was created by a Deployment, otherwise `null`
`outcome_evaluations`	array	Outcome evaluation results. New Sessions return `[]`
`stats`	Session stats	Session statistics
`archived_at`	string \| null	Archive time, or `null` when not archived
`created_at`	string	Creation time
`updated_at`	string	Last update time

Session responses no longer include legacy fields such as agent_id, turn_status, memory_store_ids, or usage.

Agent reference

agent in create requests can be either a string Agent ID or this object:

Field	Type	Required	Description
`id`	string	Yes	Agent ID with the `agent_` prefix
`type`	string	Yes (object form only)	Must be the literal `"agent"`. Missing or other values return 400 when the object form is used. The bare-string form (passing the Agent ID directly) skips this check
`version`	integer	No	Agent version to snapshot. Omit or pass `0` to use the latest active version

Session embedded agent

The agent returned inside a Session object is the Agent snapshot pinned to the Session, but several Agent fields are stripped before they are exposed:

created_at, updated_at — never included on the embedded Agent.
archived, archived_at — never included; the Session preserves access to the snapshot regardless of the source Agent’s archive state.
metadata — Agent-level metadata is stripped; only Session-level metadata is exposed.
instructions — replaced by system.

For a coordinator multi-agent setup, agent.multiagent.agents[] is hydrated server-side from stub {type, id, version} references into full Agent definitions (see Multiagent roster element). Inside a Session Thread object, the agent field additionally drops the multiagent block — coordinator threads only carry the per-agent snapshot.

`agent.model.effective_context_window`

Sessions return an additional response-only effective_context_window (int64, in tokens) inside agent.model. It is the runtime-resolved context window the Session will use for this Agent (after applying environment-level overrides). Absent or non-positive values are omitted; clients should treat the field as informational.

Session resource

resources[] is a union distinguished by type.

File resource

Field	Type	Required	Description
`id`	string	Response only	Resource ID
`type`	string	Yes	`"file"`
`file_id`	string	Yes	File ID with the `file_` prefix. The file must be ready
`mount_path`	string	No	Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>` when omitted
`created_at`	string	Response only	Resource creation time
`updated_at`	string	Response only	Resource update time

GitHub repository resource

Field	Type	Required	Description
`id`	string	Response only	Resource ID
`type`	string	Yes	`"github_repository"`
`url`	string	Yes	Repository URL
`authorization_token`	string	Yes (write only)	GitHub token used to access the repository. It is not returned in responses
`mount_path`	string	No	Clone target path in the container. Defaults from the repository name when omitted
`checkout`	object	No	Git checkout target, for example `{"type":"branch","name":"main"}`
`created_at`	string	Response only	Resource creation time
`updated_at`	string	Response only	Resource update time

Memory Store resource

Field	Type	Required	Description
`type`	string	Yes	`"memory_store"`
`memory_store_id`	string	Yes	Memory Store ID with the `memstore_` prefix
`access`	string \| null	No	Optional access mode. Allowed values: `"read_write"`, `"read_only"`. Empty string or omitted means default (no override)
`instructions`	string \| null	No	Optional instructions stored on the Session resource. Maximum 4096 characters
`name`	string \| null	Response only	Current Memory Store name when available
`description`	string	Response only	Current Memory Store description when available
`mount_path`	string \| null	Response only	Current implementation returns `null` unless an existing resource snapshot contains a value

Memory Store resources do not include id, created_at, or updated_at fields.

Session stats

Field	Type	Description
`active_seconds`	number	Active processing time in seconds. New Sessions start at `0`
`duration_seconds`	number	Session duration in seconds. New Sessions start at `0`

Multiagent roster element

When the embedded Agent declares multiagent.type = "coordinator", every entry inside agent.multiagent.agents[] returned by Session endpoints is hydrated from the original stub references into a full Agent definition (subject to the same field stripping as the Session embedded agent, and additionally without its own multiagent field).

Field	Type	Description
`type`	string	`"agent"` for a sibling Agent reference, or `"self"` for the coordinator itself
`id`	string	Agent ID. Present for `type = "agent"`; mirrors the coordinator’s own ID when `type = "self"`
`version`	integer	Pinned Agent version. Present for `type = "agent"`
`name`	string	Hydrated Agent name
`description`	string \| null	Hydrated Agent description
`system`	string	Hydrated Agent system prompt (replaces `instructions`)
`model`	string \| object	Same shape as on the embedded Agent, including `effective_context_window` when set
Other Agent fields	varies	Tools, MCP servers, skills, and other Agent fields, with the same field stripping rules as the embedded Agent

Stub references that fail to resolve (for example, the referenced Agent version no longer exists) are returned unchanged.

Event object

Events returned by send, list, and stream endpoints are event-specific JSON objects. Public event responses expose only the Claude-compatible fields for each event type.

Field	Type	Description
`id`	string	Event ID with the `evt_` prefix
`type`	string	Event type
`processed_at`	string	Present when the event has been processed. Many agent-generated events omit this field.

Depending on type, an event may also include fields such as content, input, name, tool_use_id, mcp_tool_use_id, custom_tool_use_id, result, deny_message, rubric, outcome_id, session_thread_id, stop_reason, error, or usage.

Incremental streaming event types

Incremental streaming is controlled by the Session creation field incremental_streaming_enabled; it is not selected by a stream request parameter. When the flag is false or omitted, list and stream endpoints continue to expose only the existing full public events. When the flag is true, the same endpoints can also expose these incremental event types: agent.message_start, agent.content_block_start, agent.content_block_delta, agent.content_block_stop, agent.message_delta, and agent.message_stop. These are the only top-level incremental event types. Names such as text_delta, thinking_delta, input_json_delta, and tool_output_delta are not event type values; they appear only as delta.type inside agent.content_block_delta.

Event type	Key fields	Description
`agent.message_start`	`message_id`, `message`	Starts an assistant message. `message` follows the provider raw stream message shape and initially has empty `content`
`agent.content_block_start`	`message_id`, `index`, `content_block`	Starts one content block, such as text, thinking, redacted thinking, or tool use
`agent.content_block_delta`	`message_id`, `index`, `delta`	Carries a delta for the content block at `index`
`agent.content_block_stop`	`message_id`, `index`	Ends the content block at `index`
`agent.message_delta`	`message_id`, `delta`, `usage`	Carries message-level deltas such as `stop_reason`, `stop_sequence`, optional usage, and optional context management
`agent.message_stop`	`message_id`	Ends the assistant message

Incremental events may also include session_id, session_thread_id, turn_id, parent_tool_use_id, and processed_at when available. Supported agent.content_block_delta.delta.type values:

`delta.type`	Fields	Notes
`text_delta`	`text`	Text output chunk
`thinking_delta`	`thinking`	Thinking chunk when the model/provider emits it
`signature_delta`	`signature`	Signature chunk for a thinking block when available
`input_json_delta`	`partial_json`	Tool input JSON chunk. This is the wire shape for the product-level tool input delta concept
`tool_output_delta`	varies	Reserved for future tool output streaming. Current implementations return full tool results through `agent.tool_result` instead

Example agent.content_block_delta:

{
  "id": "evt_019efd3b90007c9b88be2a4e6d8c52a0",
  "type": "agent.content_block_delta",
  "session_id": "sess_019efd3b89d57bd18be423420cf5683f",
  "session_thread_id": "sthr_019efd3b89ff7ba19ddef9174cedba52",
  "turn_id": "turn_019efd3b8a117ca3a7f6b8bfbb4a4bb1",
  "message_id": "msg_019efd3b8c0d7d48a970f01dd6117d11",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "Hello"
  },
  "processed_at": "2026-06-25T05:23:31.123Z"
}

Client event request types

POST /api/v1/cloud/sessions/{session_id}/events accepts exactly these client-sent event types:

Type	Required fields	Notes
`user.message`	`content`	`content` must be a non-empty array of content blocks
`user.interrupt`	none	`session_thread_id` is optional and is echoed as `null` when omitted
`user.tool_confirmation`	`tool_use_id`, `result`	`result` must be `allow` or `deny`; `deny_message` is optional
`user.tool_result`	`tool_use_id`	Use this to return a built-in tool result; `content` and `is_error` are optional
`user.custom_tool_result`	`custom_tool_use_id`	`content` and `is_error` are optional
`user.define_outcome`	`description`, `rubric`	`rubric` is an object such as `{"type":"text","content":"..."}` or `{"type":"file","file_id":"file_..."}`; `max_iterations` is optional
`system.message`	`content`	`content` must be a non-empty array of text content blocks; the event must follow a user/tool result event

Public event types

List and stream endpoints can expose these event types: user.message, user.interrupt, user.tool_confirmation, user.custom_tool_result, user.define_outcome, user.tool_result, system.message, agent.custom_tool_use, agent.mcp_tool_result, agent.mcp_tool_use, agent.message, agent.message_start, agent.content_block_start, agent.content_block_delta, agent.content_block_stop, agent.message_delta, agent.message_stop, agent.thinking, agent.thread_context_compacted, agent.thread_message_received, agent.thread_message_sent, agent.tool_result, agent.tool_use, session.deleted, session.error, session.status_idle, session.status_rescheduled, session.status_running, session.status_terminated, session.thread_created, session.thread_status_idle, session.thread_status_rescheduled, session.thread_status_running, session.thread_status_terminated, session.updated, span.model_request_start, span.model_request_end, span.outcome_evaluation_start, span.outcome_evaluation_ongoing, and span.outcome_evaluation_end.

Session Thread object

In managed-agent scenarios, each thread within a Session is represented by this structure.

Field	Type	Description
`id`	string	Thread ID with the `sthr_` prefix
`type`	string	Always `"session_thread"`
`session_id`	string	Owning Session ID
`parent_thread_id`	string \| null	Parent thread ID. `null` for the coordinator thread
`agent`	object	Agent snapshot used by this thread. Same shape as the Session embedded agent, with the `multiagent` block additionally removed
`status`	string	Thread lifecycle status: `running`, `idle`, `rescheduling`, or `terminated`
`stats`	object \| null	Thread statistics. Current implementation returns `null`
`archived_at`	string \| null	Archive time, or `null` when not archived
`created_at`	string	Creation time
`updated_at`	string	Last update time

Thread responses no longer include legacy fields such as agent_id, agent_version, name, role, stop_reason, created_by_tool_use_id, or usage.

Start a session

Run an agent against an environment as a stateful conversation.

​Session object

​Agent reference

​Session embedded agent

​agent.model.effective_context_window

​Session resource

​File resource

​GitHub repository resource

​Memory Store resource

​Session stats

​Multiagent roster element

​Event object

​Incremental streaming event types

​Client event request types

​Public event types

​Session Thread object

​Related