Session & Event data structures

Reference for the Session and Event data structures used by the Forward Session API.

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": false,
  "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 legacy incremental streaming events are enabled for this Session. Defaults to\ false\ if omitted at creation, and cannot be changed after creation. This feature is retained for backward compatibility; new integrations should use event_deltas[] when subscribing to the event stream.
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	thinking, text
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
event_start	event
event_delta	event_id, delta
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, event_start, event_delta, 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.

event_start and event_delta are only returned when subscribing to SSE with event_deltas[].

Incremental streaming events

Forward currently supports two incremental streaming mechanisms:

• Event delta streaming (recommended): Subscribe with event_deltas[] when connecting to the Session Event Stream.
• Legacy incremental streaming: Controlled by the incremental_streaming_enabled field set at Session creation. Retained for backward compatibility but not recommended for new integrations.

Event delta streaming

Event delta streaming is enabled by passing the event_deltas[] query parameter when subscribing to the Session Event Stream. It supports repeated parameters with the following allowed values:

event_deltas[] value	Description
agent.message	Subscribe to incremental content of assistant text messages.
agent.thinking	Subscribe to incremental content of thinking.

When enabled, the SSE stream may additionally return two top-level Event types:

Event type	Key fields	Description
event_start	event	Indicates a public event has started generating. event only retains id, type, name, mcp_server_name.
event_delta	event_id, delta	An incremental fragment of a public event. event_id references the corresponding event.

event_start.event fields:

Field	Type	Description
id	string	The Event ID of the corresponding event.
type	string	The public Event type, currently agent.message or agent.thinking.
name	string	Reserved field; not typically returned for current event_deltas[] selectors.
mcp_server_name	string	Reserved field; not typically returned for current event_deltas[] selectors.

event_delta.delta fields:

Field	Type	Description
type	string	Delta type, e.g. content_delta.
index	integer	Content block index.
content	object	Incremental content. Currently only exposes type and text.
content.type	string	Content type, e.g. text or thinking.
content.text	string	Incremental text fragment.

event_start example:

{
  "id": "evt_xxx",
  "type": "event_start",
  "session_id": "sess_xxx",
  "event": {
    "id": "evt_xxx",
    "type": "agent.message"
  }
}

event_delta example:

{
  "id": "evt_xxx",
  "type": "event_delta",
  "session_id": "sess_xxx",
  "event_id": "evt_xxx",
  "delta": {
    "type": "content_delta",
    "index": 0,
    "content": {
      "type": "text",
      "text": "Here"
    }
  }
}

Event delta streaming conventions:

• event_start / event_delta are only returned when subscribing to SSE with event_deltas[]; history queries do not return these events.
• The final complete public event is still returned. Clients can use event delta frames for instant display, then use the final complete event as the persisted or display-calibrated result.
• include_thinking=false filters agent.thinking event start signals and delta.content.type=thinking fragments.
• include_tool_calls=false does not affect event_deltas[] currently supported types (agent.message and agent.thinking), but still filters standard tool-use events and legacy tool input/output deltas.
• If the Session was created with incremental_streaming_enabled=true, that Session uses legacy streaming and event_deltas[] will not enable event delta streaming.

Legacy incremental streaming

Legacy incremental streaming is controlled by the incremental_streaming_enabled field set when creating the Session, not by request parameters. This feature is retained for backward compatibility but not recommended for new integrations:

• 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. Only complete public events are returned.

When legacy 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 legacy 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:

{
  "id": "evt_delta_xxx",
  "type": "agent.content_block_delta",
  "session_id": "sess_xxx",
  "message_id": "msg_xxx",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "Here"
  },
  "processed_at": "2026-06-22T11:00:01Z"
}

Legacy 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.