---
title: "Query session events"
method: POST
path: "/v1/sessions/{session_id}/events/query"
tags: ["Sessions"]
---

# Query session events

`POST /v1/sessions/{session_id}/events/query`

## Path parameters

- `session_id` string, required

## Headers

- `Notion-Version` '2026-03-11', required

## Request body

- object
  - `filter` union — A session event property filter, or an and/or compound filter nested up to three levels deep.
    - object
      - `property` 'id', required
      - `string` object, required
        - `equals` string, required
    - object
      - `property` 'type', required
      - `event_type` object, required
        - `equals` 'user.message' | 'agent.message' | 'agent.thinking' | 'agent.tool_use' | 'agent.tool_result' | 'session.status'
        - `in` string[]
    - object
      - `property` 'sequence', required
      - `number` object, required
        - `greater_than` number
        - `greater_than_or_equal_to` number
        - `less_than` number
        - `less_than_or_equal_to` number
    - object
      - `property` 'created_at', required
      - `timestamp` object, required
        - `equals` string, date-time
        - `before` string, date-time
        - `after` string, date-time
        - `on_or_before` string, date-time
        - `on_or_after` string, date-time
    - object
      - `and` union[], required
        - union
          - object
            - `property` 'id', required
            - `string` object, required
              - …
          - object
            - `property` 'type', required
            - `event_type` object, required
              - …
          - object
            - `property` 'sequence', required
            - `number` object, required
              - …
          - object
            - `property` 'created_at', required
            - `timestamp` object, required
              - …
          - object
            - `and` union[], required
              - …
          - object
            - `or` union[], required
              - …
    - object
      - `or` union[], required
        - union
          - object
            - `property` 'id', required
            - `string` object, required
              - …
          - object
            - `property` 'type', required
            - `event_type` object, required
              - …
          - object
            - `property` 'sequence', required
            - `number` object, required
              - …
          - object
            - `property` 'created_at', required
            - `timestamp` object, required
              - …
          - object
            - `and` union[], required
              - …
          - object
            - `or` union[], required
              - …
  - `sorts` object[] — Ordered sort precedence. Defaults to sequence ascending.
    - `property` 'sequence' | 'created_at', required — One of: `sequence`, `created_at`
    - `direction` 'ascending' | 'descending', required — One of: `ascending`, `descending`
  - `start_cursor` string — The continuation cursor returned by the previous page.
  - `page_size` integer — The number of events to return. Maximum: 100.

## Response `200`

- object
  - `object` 'list', required — Always `list`
  - `type` 'session_event', required — Always `session_event`
  - `session_event` object, required
  - `results` union[], required
    - union
      - object
        - `object` 'session_event', required — Always `session_event`
        - `id` string, required
        - `session_id` string, required
        - `sequence` integer, required
        - `created_at` string, required
        - `type` 'user.message', required — Always `user.message`
        - `content` union[], required
          - union
            - object
              - …
            - object
              - …
        - `created_by` object, nullable, required
          - `id` string, required
          - `type` 'user' | 'bot', required — One of: `user`, `bot`
        - `metadata` object, nullable, required
      - object
        - `object` 'session_event', required — Always `session_event`
        - `id` string, required
        - `session_id` string, required
        - `sequence` integer, required
        - `created_at` string, required
        - `type` 'agent.message', required — Always `agent.message`
        - `content` union[], required
          - union
            - object
              - …
            - object
              - …
        - `created_by` object, nullable, required
          - `id` string, required
          - `type` 'user' | 'bot', required — One of: `user`, `bot`
        - `metadata` object, nullable, required
          - `model` string, required
      - object
        - `object` 'session_event', required — Always `session_event`
        - `id` string, required
        - `session_id` string, required
        - `sequence` integer, required
        - `created_at` string, required
        - `type` 'agent.thinking', required — Always `agent.thinking`
        - `content` object[], required
          - `type` 'text', required — Always `text`
          - `text` string, required
      - object
        - `object` 'session_event', required — Always `session_event`
        - `id` string, required
        - `session_id` string, required
        - `sequence` integer, required
        - `created_at` string, required
        - `type` 'agent.tool_use', required — Always `agent.tool_use`
        - `tool_name` string, required
      - object
        - `object` 'session_event', required — Always `session_event`
        - `id` string, required
        - `session_id` string, required
        - `sequence` integer, required
        - `created_at` string, required
        - `type` 'agent.tool_result', required — Always `agent.tool_result`
        - `tool_use_id` string, required
        - `tool_name` string, required
        - `is_error` boolean, required
      - object
        - `object` 'session_event', required — Always `session_event`
        - `id` string, required
        - `session_id` string, required
        - `sequence` integer, required
        - `created_at` string, required
        - `type` 'session.status', required — Always `session.status`
        - `status` 'requires_action' | 'completed' | 'failed' | 'canceled' | 'terminated', required — One of: `requires_action`, `completed`, `failed`, `canceled`, `terminated`
        - `required_actions` object[]
          - `action_id` string, required
          - `title` string, required
          - `options` object[], required
            - `id` 'approve' | 'reject', required — One of: `approve`, `reject`
            - `label` string, required
        - `error` object
          - `code` string, required
          - `message` string, required
          - `retryable` boolean, required
  - `has_more` boolean, required
  - `next_cursor` string, nullable, required

## Other responses

- `400`
- `401`
- `403`
- `404`
- `406`
- `409`
- `429`
- `500`
- `503`
- `504`
- `529`

---

[API](https://skmtc.net/notion/apis/notion-api.md) · [All operations](https://skmtc.net/notion/apis/notion-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notion/notion-api/revisions/dee5763763b0/schema)