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)
`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 documented public 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.

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 from a self-hosted worker. `content` is optional; when present, it must be an array of content blocks. `is_error` is optional
`user.custom_tool_result`	`custom_tool_use_id`	`content` is optional; when present, it must be an array of content blocks. `is_error` is 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.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.

Event delta stream frames

A buffered event is a complete public Event object emitted after generation finishes and recorded in Session event history. It is the authoritative result. event_start and event_delta are stream-only SSE payloads used for incremental output. They are not public Event objects and do not appear in event list/history responses. Their JSON payloads have no top-level id or processed_at; the SSE id: field carries the ID of the event being streamed and can be used with Last-Event-ID.

Event start frame

An event_start frame identifies the public event whose incremental output has begun.

Field	Type	Description
`type`	string	Always `"event_start"`
`event`	object	Streamed event reference

The event object has these fields:

Field	Type	Description
`id`	string	Event ID with the `evt_` prefix. The SSE `id:`, related deltas, and buffered event use this same ID.
`type`	string	`"agent.message"` or `"agent.thinking"`

An agent.message start is followed by text event_delta frames. An agent.thinking start is start-only: no delta follows, and the buffered agent.thinking event with the same ID marks the end of that thinking phase when one is emitted.

{
  "type": "event_start",
  "event": {
    "id": "evt_00jjujk9fbnr4wkj2gh8",
    "type": "agent.message"
  }
}

Event delta frame

An event_delta frame appends text to an incrementally streamed agent.message.

Field	Type	Description
`type`	string	Always `"event_delta"`
`event_id`	string	ID from the matching `event_start.event.id` and SSE `id:` field
`delta`	object	Content delta

The delta object has these fields:

Field	Type	Description
`type`	string	Always `"content_delta"`
`index`	integer	Zero-based index of the content block being updated
`content`	object	Text fragment with `type: "text"` and a `text` string

{
  "type": "event_delta",
  "event_id": "evt_00jjujk9fbnr4wkj2gh8",
  "delta": {
    "type": "content_delta",
    "index": 0,
    "content": {
      "type": "text",
      "text": "Hello"
    }
  }
}

Model request span events

span.model_request_start marks the beginning of one model request.

Field	Type	Description
`id`	string	Event ID with the `evt_` prefix
`processed_at`	string	RFC 3339 timestamp
`type`	string	Always `"span.model_request_start"`

span.model_request_end marks completion of that model request.

Field	Type	Description
`id`	string	Event ID with the `evt_` prefix
`is_error`	boolean	Whether the model request ended with an error or cancellation
`model_request_start_id`	string	ID of the corresponding `span.model_request_start` event
`processed_at`	string	RFC 3339 timestamp
`type`	string	Always `"span.model_request_end"`

Model request span responses do not expose model usage or internal timing metadata.

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.

First steps

Define your agent

Configure agent environment

Delegate work to your agent

Manage agent context

Best Practices

API reference

Session data structures

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

Client event request types

Public event types

Event delta stream frames

Event start frame

Event delta frame

Model request span events

Session Thread object

​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

​Client event request types

​Public event types

​Event delta stream frames

​Event start frame

​Event delta frame

​Model request span events

​Session Thread object

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

Client event request types

Public event types

Event delta stream frames

Event start frame

Event delta frame

Model request span events

Session Thread object