GET /api/v1/forward/sessions/{session_id}/events
Returns session events with cursor pagination and field-level filtering. If incremental streaming is enabled for the Session, generated incremental events are also included.
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <PAT> |
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | Session ID. |
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit | integer | No | 20 | Items per page. Maximum 100. |
after_id | string | No | - | Cursor for events after the given Event ID. |
before_id | string | No | - | Cursor for events before the given Event ID. |
order | string | No | asc | Sort order: asc or desc. |
type | string | No | - | Filter by Event type. Comma-separated values are supported. |
types[] | string | No | - | Array-style Event type filter. |
include_tool_calls | boolean | No | true | Include tool call events. |
include_thinking | boolean | No | true | Include thinking events. |
Example request
Example response
HTTP 200 OKResponse fields
| Field | Type | Description |
|---|---|---|
data | array | Event objects on the current page. |
first_id | string|null | ID of the first event on this page. |
last_id | string|null | ID of the last event on this page. |
has_more | boolean | Whether more records remain. |
Event fields
| Field | Type | Description |
|---|---|---|
id | string | Event ID. |
type | string | Event type. |
session_id | string | Session ID. |
processed_at | string | Processing timestamp when available. |
content | array | Returned for message-like events. |
Event payload fields by type
The table below lists allowed payload fields in addition to the common envelope fieldsid, type, session_id, and processed_at.
| Event type | Payload fields |
|---|---|
user.message | content, file_attachments |
user.interrupt | reason, session_thread_id |
user.tool_confirmation | tool_use_id, result, deny_message, session_thread_id |
user.tool_result | tool_use_id, content, is_error, session_thread_id |
user.custom_tool_result | custom_tool_use_id, content, is_error, session_thread_id |
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, session_thread_id |
agent.tool_result | tool_use_id, content, is_error |
agent.custom_tool_use | name, input, session_thread_id |
agent.mcp_tool_use | mcp_server_name, name, input, evaluated_permission, session_thread_id |
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 |
| Unknown type | Envelope only. Runtime-private raw payload is not returned. |
Errors
| HTTP | Type | Code | Trigger |
|---|---|---|---|
| 400 | invalid_request_error | invalid_event_cursor | Cursor does not belong to this Session. |
| 400 | invalid_request_error | invalid_pagination | Pagination parameters are invalid. |
| 401 | authentication_error | authentication_required | PAT invalid or expired. |
| 404 | not_found_error | session_not_found | Session does not exist. |
Notes
- Unknown Event types do not fail the request. They are returned with the minimal envelope when available.
- Forward filters runtime-private fields such as agent IDs, environment IDs, resources, vaults, worker IDs, traces, and raw/debug/internal payloads.