Session & event data structures

Session object

This object is returned by the endpoints that create, get, list, update, and archive a Session.

{
  "id": "sess_xxx",
  "type": "session",
  "identity_id": "idn_xxx",
  "template": {
    "id": "tmpl_support",
    "type": "template",
    "name": "客服助手",
    "model": "ultimate",
    "version": 3
  },
  "source_type": "api",
  "status": "idle",
  "title": "客户支持会话",
  "incremental_streaming_enabled": true,
  "metadata": {
    "source": "web",
    "biz_id": "ticket_123"
  },
  "config": {
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "stats": {
    "active_seconds": 30,
    "duration_seconds": 3600
  },
  "usage": {
    "credits": 12.5
  },
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T11:00:00Z"
}

Field	Type	Always returned	Description
`id`	string	Yes	Session ID with the `sess_`\ prefix.
`type`	string	Yes	Always\ `"session"`.
`identity_id`	string	Yes	Forward Identity ID, representing the end-user identity that owns this Session.
`template`	object	Yes	Forward Template summary; for the fields, see Template summary.
`source_type`	string	Yes	Session source: `api`, `im`\ or\ `schedule`.
`status`	string	Yes	Session runtime status: `idle`, `running`, `rescheduling`, `canceling`\ or\ `terminated`. The archived state is expressed through\ `archived_at`.
`title`	string	Yes	Session title.
`incremental_streaming_enabled`	boolean	Yes	Whether incremental streaming events are enabled for this Session. Defaults to\ `false`\ if omitted at creation, and cannot be changed after creation.
`metadata`	object	No	Caller-defined business metadata.
`config`	object	No	Session configuration; may be omitted when not provided.
`config.environment_variables`	object	No	Session-level environment variables, as key-value pairs.
`stats`	object	No	Session statistics; for the fields, see Session stats.
`usage`	object	No	Usage information; may be omitted when the related billing module is not enabled.
`usage.credits`	number	No	Credit consumption.
`archived_at`	string \| null	Yes	Archive time; `null`\ when not archived.
`created_at`	string	Yes	Creation time, in RFC 3339 format.
`updated_at`	string	Yes	Last update time, in RFC 3339 format.

Template summary

Field	Type	Always returned	Description
`id`	string	Yes	Forward Template ID.
`type`	string	Yes	Always\ `"template"`.
`name`	string	Yes	Template name.
`model`	string	Yes	The model tier or model identifier used by the Template.
`version`	integer	Yes	Template version number.

Session stats

Field	Type	Always returned	Description
`active_seconds`	integer	No	Active processing time, in seconds; usually\ `0`\ for a new Session.
`duration_seconds`	integer	No	Session duration, in seconds; usually\ `0`\ for a new Session.

Event object

The Events returned by the endpoints are JSON objects that vary by type. Every returned Event includes the common fields, while different event types carry different payload fields.

{
  "id": "evt_xxx",
  "type": "agent.message",
  "session_id": "sess_xxx",
  "content": [
    {
      "type": "text",
      "text": "这是分析结果。"
    }
  ],
  "processed_at": "2026-06-22T11:00:03Z"
}

Field	Type	Always returned	Description
`id`	string	Yes	Event ID with the `evt_`\ prefix.
`type`	string	Yes	Event type.
`session_id`	string	Yes	The ID of the Session this Event belongs to.
`processed_at`	string	No	The time the event was processed, in RFC 3339 format. Some agent-generated events or incremental events may not include this field.

The payload fields allowed for each event type are listed below. The table does not repeat the common fields id, type, session_id, and processed_at.

Event type	Allowed fields
`user.message`	`content`
`user.interrupt`	None
`user.tool_confirmation`	`tool_use_id`, `result`, `deny_message`
`user.tool_result`	`tool_use_id`, `content`, `is_error`
`user.custom_tool_result`	`custom_tool_use_id`, `content`, `is_error`
`user.define_outcome`	`description`, `rubric`, `outcome_id`, `max_iterations`
`system.message`	`content`
`agent.message`	`content`
`agent.thinking`	None
`agent.message_start`	`message_id`, `message`
`agent.content_block_start`	`message_id`, `index`, `content_block`
`agent.content_block_delta`	`message_id`, `index`, `delta`
`agent.content_block_stop`	`message_id`, `index`
`agent.message_delta`	`message_id`, `delta`, `usage`
`agent.message_stop`	`message_id`
`agent.tool_use`	`name`, `input`, `evaluated_permission`
`agent.tool_result`	`tool_use_id`, `content`, `is_error`
`agent.custom_tool_use`	`name`, `input`
`agent.mcp_tool_use`	`mcp_server_name`, `name`, `input`, `evaluated_permission`
`agent.mcp_tool_result`	`mcp_tool_use_id`, `content`, `is_error`
`agent.artifact_delivered`	`file_id`, `original_filename`, `size`, `content_type`
`session.status_running`	None
`session.status_idle`	`stop_reason`
`session.status_terminated`	None
`session.error`	`error`
`session.updated`	`agent`, `metadata`, `title`

Event types the client can send

POST /api/v1/forward/sessions/{session_id}/events accepts only the following event types.

Type	Required fields	Description
`user.message`	`content`	User message. `content`\ must be a non-empty array of content blocks and supports block types such as\ `text`, `image`, and\ `document`.
`user.interrupt`	None	Request to interrupt the current processing.
`user.tool_confirmation`	`tool_use_id`, `result`	Tool-call confirmation. `result`\ is\ `allow`\ or\ `deny`; when denying, you may pass\ `deny_message`.
`user.tool_result`	`tool_use_id`	Returns a built-in tool result; `content`\ and\ `is_error`\ are optional.
`user.custom_tool_result`	`custom_tool_use_id`	Returns a client-defined custom tool result; `content`\ and\ `is_error`\ are optional.
`user.define_outcome`	`description`, `rubric`	Defines the expected outcome and grading criteria; `max_iterations`\ is optional.

system.message is a public Event type, but it is not open as a Forward client write event.

Public event types

When querying history and subscribing to the SSE event stream, you may receive the following public event types: user.message, user.interrupt, user.tool_confirmation, user.tool_result, user.custom_tool_result, user.define_outcome, system.message, agent.message, agent.thinking, agent.message_start, agent.content_block_start, agent.content_block_delta, agent.content_block_stop, agent.message_delta, agent.message_stop, agent.tool_use, agent.tool_result, agent.custom_tool_use, agent.mcp_tool_use, agent.mcp_tool_result, agent.artifact_delivered, session.status_running, session.status_idle, session.status_terminated, session.error, and session.updated.

Incremental streaming events

Whether incremental streaming events are exposed is controlled by the incremental_streaming_enabled field set when creating the Session, not by the request parameters of history queries or SSE subscriptions:

true: The event stream returns assistant output fragments before the final complete agent.message; history queries also return the same batch of incremental events.
false or omitted: Normal mode is kept, returning only complete public events and no incremental events.

When incremental streaming is enabled, the final complete agent.message is still returned. The client can use incremental events for instant display, then use the final agent.message as the persisted or display-calibrated result. There are only the following 6 top-level incremental event types:

Event type	Key fields	Description
`agent.message_start`	`message_id`, `message`	Starts an assistant message.
`agent.content_block_start`	`message_id`, `index`, `content_block`	Starts a content block, such as text, thinking, or tool use.
`agent.content_block_delta`	`message_id`, `index`, `delta`	Carries an incremental fragment 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 a message-level increment, such as\ `stop_reason`, `stop_sequence`, or usage information.
`agent.message_stop`	`message_id`	Ends an assistant message.

text_delta, thinking_delta, signature_delta, input_json_delta, and tool_output_delta are not top-level Event types; they only appear as agent.content_block_delta.delta.type.

`delta.type`	Field	Description
`text_delta`	`text`	A text output fragment; the client can append\ `delta.text`\ to reconstruct the text.
`thinking_delta`	`thinking`	A thinking fragment when the model or provider outputs thinking.
`signature_delta`	`signature`	A signature fragment of the thinking block, surfaced when present.
`input_json_delta`	`partial_json`	A JSON fragment of the tool input parameters.
`tool_output_delta`	varies	Reserved for future streaming of tool output; currently the complete\ `agent.tool_result`\ still takes precedence.

agent.content_block_delta example:

1{2  "id": "evt_delta_xxx",3  "type": "agent.content_block_delta",4  "session_id": "sess_xxx",5  "message_id": "msg_xxx",6  "index": 0,7  "delta": {8    "type": "text_delta",9    "text": "这是"10  },11  "processed_at": "2026-06-22T11:00:01Z"12}

Incremental event parsing conventions:

Both the SSE event: and the JSON data.type use public Event types.
agent.content_block_delta.index is used to distinguish between multiple content blocks.
processed_at may be missing on incremental events; the client should treat it as an optional field.
After a network interruption, you can use Last-Event-ID to carry the last received Event ID when reconnecting.
When include_thinking=false, thinking_delta, signature_delta, and recognizable thinking content block start/stop events are filtered out.
When include_tool_calls=false, input_json_delta, tool_output_delta, and recognizable tool content block start/stop events are filtered out.

​Session object

​Template summary

​Session stats

​Event object

​Event types the client can send

​Public event types

​Incremental streaming events