> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List mode sessions

> Lists sessions for a built-in or custom mode, ordered by most recent activity.
Results include only API runs created with the authenticating API key.

Use `limit`, `after`, and `before` for cursor pagination. Without these parameters, the endpoint returns legacy offset pagination.




## OpenAPI

````yaml /api/platform/v1/openapi-kapso-agent.yaml get /kapso-agent/modes/{mode}/sessions
openapi: 3.1.0
info:
  title: Kapso Agent API
  version: 0.1.0
  description: >
    Trigger runs in built-in modes with the API trigger enabled or custom modes
    with the `api` surface enabled.

    Inspect sessions, control run lifecycles, and handle approvals
    programmatically.
servers:
  - url: https://api.kapso.ai/platform/v1
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Agent Modes
    description: Discover the agent modes and which ones accept API runs
  - name: Agent Sessions
    description: List API sessions and inspect their runs
  - name: Agent Runs
    description: Create, poll, and control Kapso Agent runs
paths:
  /kapso-agent/modes/{mode}/sessions:
    get:
      tags:
        - Agent Sessions
      summary: List mode sessions
      description: >
        Lists sessions for a built-in or custom mode, ordered by most recent
        activity.

        Results include only API runs created with the authenticating API key.


        Use `limit`, `after`, and `before` for cursor pagination. Without these
        parameters, the endpoint returns legacy offset pagination.
      operationId: listAgentModeSessions
      parameters:
        - name: mode
          in: path
          required: true
          schema:
            type: string
          description: Built-in or custom mode slug
        - $ref: '#/components/parameters/LegacyPage'
        - $ref: '#/components/parameters/LegacyPerPage'
        - $ref: '#/components/parameters/CursorLimit'
        - $ref: '#/components/parameters/CursorBefore'
        - $ref: '#/components/parameters/CursorAfter'
      responses:
        '200':
          description: Sessions ordered by most recent activity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSessionListResponse'
        '400':
          description: Invalid pagination parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginationErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Unknown or inaccessible mode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    LegacyPage:
      name: page
      in: query
      deprecated: true
      description: >-
        Page number for legacy offset pagination. Use cursor pagination for new
        integrations.
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 1
    LegacyPerPage:
      name: per_page
      in: query
      description: Number of results for legacy offset pagination.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    CursorLimit:
      name: limit
      in: query
      description: Maximum number of results for cursor pagination.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    CursorBefore:
      name: before
      in: query
      description: Cursor for the previous page.
      schema:
        type: string
    CursorAfter:
      name: after
      in: query
      description: Cursor for the next page.
      schema:
        type: string
  schemas:
    AgentSessionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AgentSession'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        paging:
          $ref: '#/components/schemas/Paging'
    PaginationErrorResponse:
      type: object
      description: Invalid cursor, limit, or legacy offset window
      properties:
        error:
          type: string
          description: Present for invalid cursor parameters
        message:
          type: string
          description: Present when the legacy offset window exceeds its limit
        detail:
          type: string
          description: Instructions for switching to cursor pagination
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
    AgentSession:
      type: object
      properties:
        conversation_id:
          type: string
          format: uuid
          description: Session identifier used to continue a conversation
        title:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - active
            - paused
            - terminated
        created_at:
          type: string
          format: date-time
        run_count:
          type: integer
          minimum: 0
          description: Total API runs in the session
        latest_run:
          $ref: '#/components/schemas/SessionLatestRun'
        last_activity_at:
          type: string
          format: date-time
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
        per_page:
          type: integer
          minimum: 1
        total_pages:
          type: integer
          minimum: 0
        total_count:
          type: integer
          minimum: 0
        has_next:
          type: boolean
        total_count_estimated:
          type: boolean
          description: The total is an estimate for bounded offset pagination
    Paging:
      type: object
      properties:
        cursors:
          $ref: '#/components/schemas/PaginationCursor'
        next:
          type:
            - string
            - 'null'
          description: Cursor for the next page
        previous:
          type:
            - string
            - 'null'
          description: Cursor for the previous page
    SessionLatestRun:
      type:
        - object
        - 'null'
      properties:
        run_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/RunStatus'
        created_at:
          type: string
          format: date-time
    PaginationCursor:
      type: object
      properties:
        before:
          type:
            - string
            - 'null'
          description: Cursor for the previous page
        after:
          type:
            - string
            - 'null'
          description: Cursor for the next page
    RunStatus:
      type: string
      enum:
        - queued
        - running
        - paused
        - waiting_for_approval
        - completed
        - failed
        - cancelled
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````