Query sessions

Find agent sessions that an integration can access.

POST /v1/sessions/query

TypeScript SDK

JavaScript

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.sessions.query({
  filter: { property: "agent_id", string: { equals: "1f0c7c06-781b-4987-9986-5c8dd3028013" } },
  sorts: [{ property: "updated_at", direction: "descending" }],
  page_size: 10
})

200

{
  "object": "list",
  "type": "session",
  "session": {},
  "results": [
    {
      "object": "session",
      "id": "<string>",
      "agent_id": "<string>",
      "title": "<string>",
      "status": "queued",
      "created_by": {
        "id": "<string>",
        "type": "user"
      },
      "agent_version": {
        "id": "<string>",
        "number": 2,
        "published_at": "2023-11-07T05:31:56Z"
      },
      "models": {
        "type": "auto"
      },
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "required_actions": [
        {
          "action_id": "<string>",
          "title": "<string>",
          "options": [
            {
              "id": "approve",
              "label": "<string>"
            }
          ]
        }
      ],
      "error": {
        "code": "<string>",
        "message": "<string>",
        "retryable": true
      },
      "trigger_type": "<string>",
      "type_labels": [
        "<string>"
      ],
      "chat_user_emails": [
        "<string>"
      ],
      "tool_types": [
        "<string>"
      ],
      "tool_call_count": 1,
      "credits_used": 1,
      "runs_completed": 1,
      "message_count": 1
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}

Use filter, sorts, and query to narrow the list. Pass each next_cursor as start_cursor until has_more is false, even when results is empty.

Results include only sessions the token can read. By default, a connection token sees only the sessions its connection created. See session access rules for which sessions each token can read.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Notion-Version · enum<string> · required

The API version to use for this request. The latest version is 2026-03-11.

Available options: 2026-03-11

Body

application/json

query · string

A case-insensitive substring search over session titles.

Maximum string length: 2000

filter · object

A session property filter, or an and/or compound filter nested up to two levels deep.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Show child attributes

sorts · object[]

Ordered sort precedence. Defaults to updated_at descending.

Required array length: 1 - 2 elements

Show child attributes

start_cursor · string

The continuation cursor returned by the previous page.

page_size · integer

The number of sessions to return. Maximum: 100.

Required range: 1 <= x <= 100

Response

200

application/json

object · string · required

Always list

Allowed value: "list"

type · string · required

Always session

Allowed value: "session"

session · object · required

results · object[] · required

Sessions found in this bounded scan. Access filtering can leave this array empty while has_more is true.

Maximum array length: 100

Show child attributes

has_more · boolean · required

Whether more session candidates remain after this bounded scan.

next_cursor · string | null · required

Pass this cursor as start_cursor when has_more is true, even when results is empty.