List events

GET /v1/sessions/{session_id}/events

Returns a session’s event history, oldest first by default.

The key must have the tasks:read capability. For what each capability allows, see Keys.

Path parameters

Name	Type	Required	Default	Description
`session_id`	`string`	Yes		The ID of the session whose events to return.

Query parameters

Name	Type	Required	Default	Description
`limit`	`integer`	No	`100`	The maximum number of events to return on one page. Must be between 1 and 1000.
`order`	`string`	No	`asc`	The sort order. One of `asc` (oldest first) or `desc` (newest first).
`page`	`string`	No		The ID of the event to start from. To fetch the next page, pass the `next_page` value from the previous response. With `asc`, the page starts with the first event after this one. With `desc`, it starts with the first event before it. The event itself is not included.
`types`	`array<string>`	No		The event types to return. To pass more than one, repeat the parameter: `types[]=agent.message&types[]=session.status_idle`.
`created_at[gte]`	`string`	No		The earliest `processed_at` time to include, as an RFC 3339 timestamp. `created_at[gt]` (after), `created_at[lt]` (before) and `created_at[lte]` (at or before) filter the same field.

Response

Returns 200 with a page of events in data, in the order order sets, and a next_page value to pass as page. next_page is null when no more events match.

{
  "data": [
    {
      "type": "user.message",
      "id": "sevt_1_0",
      "processed_at": "2026-10-21T01:42:16.357Z",
      "content": [
        {
          "type": "text",
          "text": "Run this bash command and tell me the output: echo first"
        }
      ]
    },
    {
      "type": "session.status_running",
      "id": "sevt_1_1",
      "processed_at": "2026-10-21T01:42:16.357Z"
    },
    {
      "type": "agent.tool_use",
      "id": "sevt_29_0",
      "processed_at": "2026-10-21T01:42:21.908Z",
      "name": "bash",
      "input": {
        "command": "echo first"
      }
    }
  ],
  "next_page": null
}

Errors

This endpoint can return these errors as well as the common errors.

Status	`error.type`	Cause and fix
400	`invalid_request_error`	`limit` is outside 1 to 1000. Send a value from 1 to 1000.
400	`invalid_request_error`	`order` is not `asc` or `desc`. Send one of them, or omit it.
400	`invalid_request_error`	`page` is not an event ID this API issued. Send the `next_page` value from the previous response, unchanged.
400	`invalid_request_error`	A `created_at` bound is not an RFC 3339 timestamp. Send a timestamp such as `2026-10-21T01:42:16Z`.
404	`not_found_error`	No session with this ID exists, or this key can’t read it. Check the session ID.
503	`api_error`	The session’s history is still being indexed. Retry the request shortly.

Example

curl -sS "$CONTEXT_BASE_URL/v1/sessions/dd13d728-93e3-440a-874c-4efeb58c97e0/events?limit=100" -H "x-api-key: $CONTEXT_API_KEY"

for event in client.beta.sessions.events.list("dd13d728-93e3-440a-874c-4efeb58c97e0", limit=100):  # auto-paginates
    print(event.id, event.type)

for await (const event of client.beta.sessions.events.list("dd13d728-93e3-440a-874c-4efeb58c97e0", { limit: 100 })) console.log(event.id, event.type)