List event history for a Forward session.
GET /api/v1/forward/sessions/{session_id}/events
Returns session events with cursor pagination and field-level filtering. If legacy incremental streaming is enabled for the Session, generated legacy incremental events are also included; event delta stream events subscribed via event_deltas[] do not appear in history results.
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <PAT or SAT> |
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 OK
Response 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 fields id, type, session_id, and processed_at.
| Event type | Payload fields |
|---|---|
user.message | content, file_attachments |
user.interrupt | reason |
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 |
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.thread_created | session_thread_id |
session.thread_status_running | session_thread_id |
session.thread_status_idle | session_thread_id, stop_reason |
session.thread_status_rescheduled | session_thread_id |
session.thread_status_terminated | session_thread_id |
session.error | error |
session.updated | agent, metadata, title |
span.model_request_end | is_error, model_request_start_id, model_usage |
| 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 or SAT 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.