> ## Documentation Index > Fetch the complete documentation index at: https://developers.notion.com/llms.txt > Use this file to discover all available pages before exploring further. # Query sessions > Find agent sessions that an integration can access. Use `filter`, `sorts`, and `query` to narrow the list. Follow `next_cursor` until `has_more` is `false`. ## OpenAPI ````yaml post /v1/sessions/query openapi: 3.1.0 info: title: Notion API version: 1.0.0 termsOfService: >- https://notion.notion.site/Terms-and-Privacy-28ffdd083dc3473e9c2da6ec011b58ac servers: - url: https://api.notion.com security: - bearerAuth: [] tags: - name: Databases description: Database endpoints - name: Data sources description: Data source endpoints - name: Pages description: Page endpoints - name: Async tasks description: Async task endpoints - name: Blocks description: Block endpoints - name: Comments description: Comment endpoints - name: File uploads description: File upload endpoints - name: OAuth description: OAuth endpoints (basic authentication) - name: Users description: User endpoints - name: Search description: Search endpoints - name: Views description: View endpoints - name: Agents description: Agent endpoints - name: Sessions description: Session endpoints - name: Custom emojis description: Custom emoji endpoints - name: Meeting notes description: Meeting notes endpoints paths: /v1/sessions/query: post: tags: - Sessions summary: Query sessions operationId: query-sessions parameters: - $ref: '#/components/parameters/notionVersion' requestBody: required: true content: application/json: schema: type: object properties: query: type: string maxLength: 2000 description: A case-insensitive substring search over session titles. filter: oneOf: - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - agent_id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - status additionalProperties: false properties: property: type: string enum: - status status: type: object description: A session status comparison. additionalProperties: false properties: equals: type: string description: Return sessions with this status. enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated in: type: array description: Return sessions with any of these statuses. maxItems: 7 items: type: string enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated - type: object required: - property - timestamp additionalProperties: false properties: property: type: string description: The session timestamp to compare. enum: - created_at - updated_at timestamp: type: object description: A timestamp range. additionalProperties: false properties: before: type: string format: date-time description: Return sessions before this time. after: type: string format: date-time description: Return sessions after this time. on_or_before: type: string format: date-time description: Return sessions at or before this time. on_or_after: type: string format: date-time description: Return sessions at or after this time. - type: object required: - and additionalProperties: false properties: and: type: array maxItems: 100 description: Return sessions that match every child filter. items: oneOf: - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - agent_id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - status additionalProperties: false properties: property: type: string enum: - status status: type: object description: A session status comparison. additionalProperties: false properties: equals: type: string description: Return sessions with this status. enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated in: type: array description: >- Return sessions with any of these statuses. maxItems: 7 items: type: string enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated - type: object required: - property - timestamp additionalProperties: false properties: property: type: string description: The session timestamp to compare. enum: - created_at - updated_at timestamp: type: object description: A timestamp range. additionalProperties: false properties: before: type: string format: date-time description: Return sessions before this time. after: type: string format: date-time description: Return sessions after this time. on_or_before: type: string format: date-time description: Return sessions at or before this time. on_or_after: type: string format: date-time description: Return sessions at or after this time. - type: object required: - and additionalProperties: false properties: and: type: array maxItems: 100 description: >- Return sessions that match every child filter. items: oneOf: - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - agent_id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - status additionalProperties: false properties: property: type: string enum: - status status: type: object description: A session status comparison. additionalProperties: false properties: equals: type: string description: Return sessions with this status. enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated in: type: array description: >- Return sessions with any of these statuses. maxItems: 7 items: type: string enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated - type: object required: - property - timestamp additionalProperties: false properties: property: type: string description: The session timestamp to compare. enum: - created_at - updated_at timestamp: type: object description: A timestamp range. additionalProperties: false properties: before: type: string format: date-time description: Return sessions before this time. after: type: string format: date-time description: Return sessions after this time. on_or_before: type: string format: date-time description: Return sessions at or before this time. on_or_after: type: string format: date-time description: Return sessions at or after this time. - type: object required: - or additionalProperties: false properties: or: type: array maxItems: 100 description: >- Return sessions that match any child filter. items: oneOf: - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - agent_id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - status additionalProperties: false properties: property: type: string enum: - status status: type: object description: A session status comparison. additionalProperties: false properties: equals: type: string description: Return sessions with this status. enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated in: type: array description: >- Return sessions with any of these statuses. maxItems: 7 items: type: string enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated - type: object required: - property - timestamp additionalProperties: false properties: property: type: string description: The session timestamp to compare. enum: - created_at - updated_at timestamp: type: object description: A timestamp range. additionalProperties: false properties: before: type: string format: date-time description: Return sessions before this time. after: type: string format: date-time description: Return sessions after this time. on_or_before: type: string format: date-time description: Return sessions at or before this time. on_or_after: type: string format: date-time description: Return sessions at or after this time. - type: object required: - or additionalProperties: false properties: or: type: array maxItems: 100 description: Return sessions that match any child filter. items: oneOf: - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - agent_id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - status additionalProperties: false properties: property: type: string enum: - status status: type: object description: A session status comparison. additionalProperties: false properties: equals: type: string description: Return sessions with this status. enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated in: type: array description: >- Return sessions with any of these statuses. maxItems: 7 items: type: string enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated - type: object required: - property - timestamp additionalProperties: false properties: property: type: string description: The session timestamp to compare. enum: - created_at - updated_at timestamp: type: object description: A timestamp range. additionalProperties: false properties: before: type: string format: date-time description: Return sessions before this time. after: type: string format: date-time description: Return sessions after this time. on_or_before: type: string format: date-time description: Return sessions at or before this time. on_or_after: type: string format: date-time description: Return sessions at or after this time. - type: object required: - and additionalProperties: false properties: and: type: array maxItems: 100 description: >- Return sessions that match every child filter. items: oneOf: - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - agent_id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - status additionalProperties: false properties: property: type: string enum: - status status: type: object description: A session status comparison. additionalProperties: false properties: equals: type: string description: Return sessions with this status. enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated in: type: array description: >- Return sessions with any of these statuses. maxItems: 7 items: type: string enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated - type: object required: - property - timestamp additionalProperties: false properties: property: type: string description: The session timestamp to compare. enum: - created_at - updated_at timestamp: type: object description: A timestamp range. additionalProperties: false properties: before: type: string format: date-time description: Return sessions before this time. after: type: string format: date-time description: Return sessions after this time. on_or_before: type: string format: date-time description: Return sessions at or before this time. on_or_after: type: string format: date-time description: Return sessions at or after this time. - type: object required: - or additionalProperties: false properties: or: type: array maxItems: 100 description: >- Return sessions that match any child filter. items: oneOf: - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - string additionalProperties: false properties: property: type: string enum: - agent_id string: type: object description: An exact string comparison. required: - equals additionalProperties: false properties: equals: type: string description: Return sessions with this exact value. - type: object required: - property - status additionalProperties: false properties: property: type: string enum: - status status: type: object description: A session status comparison. additionalProperties: false properties: equals: type: string description: Return sessions with this status. enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated in: type: array description: >- Return sessions with any of these statuses. maxItems: 7 items: type: string enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated - type: object required: - property - timestamp additionalProperties: false properties: property: type: string description: The session timestamp to compare. enum: - created_at - updated_at timestamp: type: object description: A timestamp range. additionalProperties: false properties: before: type: string format: date-time description: Return sessions before this time. after: type: string format: date-time description: Return sessions after this time. on_or_before: type: string format: date-time description: Return sessions at or before this time. on_or_after: type: string format: date-time description: Return sessions at or after this time. description: >- A session property filter, or an and/or compound filter nested up to two levels deep. sorts: type: array items: type: object properties: property: type: string enum: - created_at - updated_at description: 'One of: `created_at`, `updated_at`' direction: type: string enum: - ascending - descending description: 'One of: `ascending`, `descending`' additionalProperties: false required: - property - direction maxItems: 2 minItems: 1 description: Ordered sort precedence. Defaults to updated_at descending. start_cursor: type: string description: The continuation cursor returned by the previous page. page_size: type: integer minimum: 1 maximum: 100 description: 'The number of sessions to return. Maximum: 100.' additionalProperties: false responses: '200': description: '' content: application/json: schema: type: object properties: object: type: string const: list description: Always `list` type: type: string const: session description: Always `session` session: type: object properties: {} additionalProperties: false results: type: array items: type: object properties: object: type: string const: session description: Always `session` id: type: string agent_id: type: string title: type: string status: type: string enum: - queued - in_progress - requires_action - completed - failed - canceled - terminated description: >- One of: `queued`, `in_progress`, `requires_action`, `completed`, `failed`, `canceled`, `terminated` created_by: type: object properties: id: type: string type: type: string enum: - user - bot description: 'One of: `user`, `bot`' additionalProperties: false required: - id - type agent_version: oneOf: - type: object properties: id: type: string number: type: integer minimum: 1 published_at: type: string format: date-time additionalProperties: false required: - id - number - published_at - type: 'null' models: oneOf: - type: object properties: type: type: string const: auto description: Always `auto` additionalProperties: false required: - type - type: object properties: type: type: string const: pinned description: Always `pinned` ids: type: array items: oneOf: - type: string - type: 'null' additionalProperties: false required: - type - ids created_at: type: string format: date-time updated_at: type: string format: date-time required_actions: type: array items: type: object properties: action_id: type: string title: type: string options: type: array items: type: object properties: id: type: string enum: - approve - reject description: 'One of: `approve`, `reject`' label: type: string additionalProperties: false required: - id - label maxItems: 100 additionalProperties: false required: - action_id - title - options error: type: object properties: code: type: string message: type: string retryable: type: boolean additionalProperties: false required: - code - message - retryable trigger_type: type: string type_labels: oneOf: - type: array items: type: string - type: 'null' chat_user_emails: oneOf: - type: array items: type: string - type: 'null' tool_types: oneOf: - type: array items: type: string - type: 'null' tool_call_count: oneOf: - type: integer minimum: 0 - type: 'null' credits_used: oneOf: - type: number minimum: 0 - type: 'null' runs_completed: oneOf: - type: integer minimum: 0 - type: 'null' message_count: oneOf: - type: integer minimum: 0 - type: 'null' additionalProperties: false required: - object - id - agent_id - title - status - created_by - agent_version - models - created_at - updated_at maxItems: 100 has_more: type: boolean next_cursor: oneOf: - type: string - type: 'null' additionalProperties: false required: - object - type - session - results - has_more - next_cursor '400': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_400' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_401' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_403' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_404' '406': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_406' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_409' '429': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_429' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_500' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_503' '504': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_504' '529': description: '' content: application/json: schema: $ref: '#/components/schemas/error_api_529' x-codeSamples: - lang: javascript label: TypeScript SDK source: |- 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 }) components: parameters: notionVersion: name: Notion-Version in: header required: true schema: enum: - '2026-03-11' description: >- The [API version](/reference/versioning) to use for this request. The latest version is `2026-03-11`. schemas: error_api_400: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - invalid_json - invalid_request_url - invalid_request - missing_version - invalid_beta - validation_error - invalid_credit_limit status: const: 400 required: - code - status additionalProperties: false error_api_401: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - unauthorized status: const: 401 required: - code - status additionalProperties: false error_api_403: oneOf: - allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - restricted_resource - status_change_not_allowed status: const: 403 required: - code - status additionalProperties: false - allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: const: workspace_credits_exhausted status: const: 403 additional_data: type: object properties: tool_error_code: const: workspace_credits_exhausted tool_error_class: const: entitlement_required tool_error_retryable: const: 'false' recovery_kind: enum: - contact_workspace_owner - open_workspace_credit_settings description: The recovery action selected by Notion for the caller. recovery_url: type: string format: uri description: >- Present when recovery_kind directs the caller to a settings page. required: - tool_error_code - tool_error_class - tool_error_retryable - recovery_kind additionalProperties: oneOf: - type: string - type: array items: type: string required: - code - status - additional_data - allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: const: agent_credit_limit_reached status: const: 403 additional_data: type: object properties: tool_error_code: const: agent_credit_limit_reached tool_error_class: const: entitlement_required tool_error_retryable: const: 'false' recovery_kind: enum: - contact_workspace_owner - none - open_agent_settings - request_agent_limit_increase - request_pending description: The recovery action selected by Notion for the caller. recovery_url: type: string format: uri description: >- Present when recovery_kind directs the caller to a settings page. required: - tool_error_code - tool_error_class - tool_error_retryable - recovery_kind additionalProperties: oneOf: - type: string - type: array items: type: string required: - code - status - additional_data error_api_404: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - object_not_found - directory_not_found status: const: 404 required: - code - status additionalProperties: false error_api_406: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - row_limit_exceeded status: const: 406 required: - code - status additionalProperties: false error_api_409: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - conflict_error - idempotency_key_reused - agent_deleted status: const: 409 required: - code - status additionalProperties: false error_api_429: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - rate_limited status: const: 429 required: - code - status additionalProperties: false error_api_500: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - internal_server_error status: const: 500 required: - code - status additionalProperties: false error_api_503: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - service_unavailable status: const: 503 required: - code - status additionalProperties: false error_api_504: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - gateway_timeout status: const: 504 required: - code - status additionalProperties: false error_api_529: allOf: - $ref: '#/components/schemas/publicApiCommonErrorResponse' - type: object properties: code: enum: - service_overload status: const: 529 required: - code - status additionalProperties: false publicApiCommonErrorResponse: type: object properties: object: const: error message: type: string additional_data: type: object additionalProperties: oneOf: - type: string - type: array items: type: string required: - object - message securitySchemes: bearerAuth: type: http scheme: bearer ````