> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List session events

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

```bash theme={null}
curl -s -X GET 'https://api.qoder.com/api/v1/forward/sessions/sess_xxx/events?limit=20&order=asc' \
  -H "Authorization: Bearer $QODER_PAT"
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "evt_xxx",
      "type": "agent.message",
      "session_id": "sess_xxx",
      "content": [
        {
          "type": "text",
          "text": "Here is the analysis result."
        }
      ],
      "processed_at": "2026-06-22T11:00:03Z"
    }
  ],
  "first_id": "evt_xxx",
  "last_id": "evt_xxx",
  "has_more": false
}
```

## 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`, `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.

## Related

<CardGroup cols={2}>
  <Card title="Send session events" icon="paper-plane" href="/cloud-agents/api/forward/sessions/send-events" />

  <Card title="Stream session events" icon="radio" href="/cloud-agents/api/forward/sessions/stream-events" />
</CardGroup>