---
title: "Query sessions"
method: POST
path: "/v1/sessions/query"
tags: ["Sessions"]
---

# Query sessions

`POST /v1/sessions/query`

## Headers

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

## Request body

- object
  - `query` string — A case-insensitive substring search over session titles.
  - `filter` union — A session property filter, or an and/or compound filter nested up to two levels deep.
    - object
      - `property` 'id', required
      - `string` object, required — An exact string comparison.
        - `equals` string, required — Return sessions with this exact value.
    - object
      - `property` 'agent_id', required
      - `string` object, required — An exact string comparison.
        - `equals` string, required — Return sessions with this exact value.
    - object
      - `property` 'status', required
      - `status` object, required — A session status comparison.
        - `equals` 'queued' | 'in_progress' | 'requires_action' | 'completed' | 'failed' | 'canceled' | 'terminated' — Return sessions with this status.
        - `in` string[] — Return sessions with any of these statuses.
    - object
      - `property` 'created_at' | 'updated_at', required — The session timestamp to compare.
      - `timestamp` object, required — A timestamp range.
        - `before` string, date-time — Return sessions before this time.
        - `after` string, date-time — Return sessions after this time.
        - `on_or_before` string, date-time — Return sessions at or before this time.
        - `on_or_after` string, date-time — Return sessions at or after this time.
    - object
      - `and` union[], required — Return sessions that match every child filter.
        - union
          - object
            - `property` 'id', required
            - `string` object, required — An exact string comparison.
              - …
          - object
            - `property` 'agent_id', required
            - `string` object, required — An exact string comparison.
              - …
          - object
            - `property` 'status', required
            - `status` object, required — A session status comparison.
              - …
          - object
            - `property` 'created_at' | 'updated_at', required — The session timestamp to compare.
            - `timestamp` object, required — A timestamp range.
              - …
          - object
            - `and` union[], required — Return sessions that match every child filter.
              - …
          - object
            - `or` union[], required — Return sessions that match any child filter.
              - …
    - object
      - `or` union[], required — Return sessions that match any child filter.
        - union
          - object
            - `property` 'id', required
            - `string` object, required — An exact string comparison.
              - …
          - object
            - `property` 'agent_id', required
            - `string` object, required — An exact string comparison.
              - …
          - object
            - `property` 'status', required
            - `status` object, required — A session status comparison.
              - …
          - object
            - `property` 'created_at' | 'updated_at', required — The session timestamp to compare.
            - `timestamp` object, required — A timestamp range.
              - …
          - object
            - `and` union[], required — Return sessions that match every child filter.
              - …
          - object
            - `or` union[], required — Return sessions that match any child filter.
              - …
  - `sorts` object[] — Ordered sort precedence. Defaults to updated_at descending.
    - `property` 'created_at' | 'updated_at', required — One of: `created_at`, `updated_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 sessions to return. Maximum: 100.

## Response `200`

- object
  - `object` 'list', required — Always `list`
  - `type` 'session', required — Always `session`
  - `session` object, required
  - `results` object[], required
    - `object` 'session', required — Always `session`
    - `id` string, required
    - `agent_id` string, required
    - `title` string, required
    - `status` 'queued' | 'in_progress' | 'requires_action' | 'completed' | 'failed' | 'canceled' | 'terminated', required — One of: `queued`, `in_progress`, `requires_action`, `completed`, `failed`, `canceled`, `terminated`
    - `created_by` object, required
      - `id` string, required
      - `type` 'user' | 'bot', required — One of: `user`, `bot`
    - `agent_version` object, nullable, required
      - `id` string, required
      - `number` integer, required
      - `published_at` string, date-time, required
    - `models` union, required
      - object
        - `type` 'auto', required — Always `auto`
      - object
        - `type` 'pinned', required — Always `pinned`
        - `ids` string[], required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `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
    - `trigger_type` string
    - `type_labels` string[], nullable
    - `chat_user_emails` string[], nullable
    - `tool_types` string[], nullable
    - `tool_call_count` integer, nullable
    - `credits_used` number, nullable
    - `runs_completed` integer, nullable
    - `message_count` integer, nullable
  - `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)