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

# List AI sessions

> Returns a marker-paginated list of the AI sessions that the authenticated user can read and that were created through the Box public API. Entries are ordered by `sort` and `direction`, defaulting to `updated_at` descending so the most recently active session appears first.

The access token must have both the `ai.readwrite` and `root_readwrite` scopes.

A page may contain fewer than `limit` entries while further pages remain. Treat a non-null `next_marker` as the only signal that more results exist.

> [!NOTE]
>
> Learn more about [Box SDK versioning strategy](https://developer.box.com/guides/tooling/sdks/sdk-versioning.md).


## OpenAPI

````yaml box-openapi-v2026.0.json GET /ai_sessions
openapi: 3.0.2
info:
  title: Box Platform API
  description: >-
    [Box Platform](https://developer.box.com) provides functionality to provide
    access to content stored within [Box](https://box.com). It provides
    endpoints for basic manipulation of files and folders, management of users
    within an enterprise, as well as more complex topics such as legal holds and
    retention policies.
  termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9
  contact:
    name: Box, Inc
    url: https://developer.box.com
    email: devrel@box.com
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '2026.0'
  x-box-commit-hash: d3324c11ac
servers:
  - url: https://api.box.com/2.0
    description: Box Platform API server.
security:
  - OAuth2Security: []
tags:
  - name: AI Sessions
    description: >-
      Endpoints for listing and deleting AI sessions, which hold the
      conversation state for interactions with Box AI agents.
    x-box-tag: ai_sessions
  - name: Automate Workflows
    description: Endpoints for listing and manually starting Automate workflow actions.
    x-box-tag: automate_workflows
  - name: Convert to Box Note
    description: Create Box Notes from supported source content (for example Markdown).
    x-box-tag: notes
  - name: Document Split
    description: >-
      A set of endpoints used to split a paginated source document into multiple
      files based on user-defined or AI-generated page ranges.
    x-box-tag: document_split
  - name: Query
    description: Query for your items.
    x-box-tag: query
  - name: Shuttle
    description: >-
      Endpoints for managing Box Shuttle, the service that migrates content into
      Box from external sources. Use these endpoints to manage the systems that
      Shuttle migrates content from and the migration jobs that Shuttle runs.
    x-box-tag: shuttle
externalDocs:
  description: Box Developer Documentation.
  url: https://developer.box.com
paths:
  /ai_sessions:
    get:
      tags:
        - AI Sessions
      summary: List AI sessions
      description: >-
        Returns a marker-paginated list of the AI sessions that the
        authenticated user can read and that were created through the Box public
        API. Entries are ordered by `sort` and `direction`, defaulting to
        `updated_at` descending so the most recently active session appears
        first.


        The access token must have both the `ai.readwrite` and `root_readwrite`
        scopes.


        A page may contain fewer than `limit` entries while further pages
        remain. Treat a non-null `next_marker` as the only signal that more
        results exist.
      operationId: get_ai_sessions_v2026.0
      parameters:
        - $ref: '#/components/parameters/BoxVersionHeader'
        - name: source
          in: query
          description: >-
            Restricts the list to AI sessions with this origin. The only
            supported value is `api`.
          required: true
          schema:
            type: string
            enum:
              - api
          example: api
        - name: marker
          in: query
          description: >-
            The position marker at which to begin returning results, as returned
            in `next_marker` by the previous page. Omit it for the first page.
            All other parameters must match the request that returned the
            marker.
          required: false
          schema:
            type: string
          example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
        - name: sort
          in: query
          description: >-
            The field to sort results by. Possible values are `created_at`,
            `updated_at`, and `name`. Default is `updated_at`, which advances on
            each turn of session activity.
          required: false
          schema:
            type: string
            default: updated_at
            enum:
              - created_at
              - updated_at
              - name
          example: updated_at
        - name: direction
          in: query
          description: >-
            The direction to sort results in, either ascending (`asc`) or
            descending (`desc`). Default is `desc`.
          required: false
          schema:
            type: string
            default: desc
            enum:
              - asc
              - desc
          example: desc
        - name: limit
          in: query
          description: >-
            The maximum number of AI sessions to return per page. The maximum is
            `100`; larger values are treated as `100`. The server may return
            fewer entries than requested.
          required: false
          schema:
            type: integer
            format: int32
            default: 100
            minimum: 1
          example: 100
        - name: client_ids
          in: query
          description: >-
            A comma-separated list of OAuth client IDs. Restricts the list to AI
            sessions created by any of these applications. Client IDs that match
            no application are ignored, so the response is an empty list if none
            of them match. Empty entries are ignored, and an empty value is
            treated as if the parameter were not provided.
          required: false
          schema:
            type: array
            items:
              type: string
          example:
            - ly1nj6n11vionaie65emwzk575hnnmrk
          explode: false
      responses:
        '200':
          description: Returns a paginated list of AI sessions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiSessions'
        '400':
          description: >-
            Returned with the `bad_request` code when `source` is missing, or
            when `source`, `marker`, `sort`, `direction`, or `limit` holds an
            unsupported value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '401':
          description: >-
            Returned when the access token provided in the `Authorization`
            header is not recognized or not provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: >-
            Returned with the `insufficient_scope` code when the access token
            does not have both the `ai.readwrite` and `root_readwrite` scopes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '429':
          description: >-
            Returned with the `too_many_requests` code when the user has sent
            too many requests in a given amount of time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  parameters:
    BoxVersionHeader:
      name: box-version
      in: header
      description: Version header.
      allowEmptyValue: false
      required: true
      schema:
        type: string
        enum:
          - '2026.0'
      example: '2026.0'
  schemas:
    AiSessions:
      description: A paginated list of AI sessions.
      type: object
      allOf:
        - required:
            - entries
            - limit
            - next_marker
          properties:
            entries:
              description: >-
                A list of AI sessions. The list is empty when there are no
                results.
              type: array
              items:
                $ref: '#/components/schemas/AiSession'
        - type: object
          description: The part of an API response that describes marker based pagination.
          properties:
            limit:
              description: >-
                The limit that was used for these entries. This will be the same
                as the `limit` query parameter unless that value exceeded the
                maximum value allowed. The maximum value varies by API.
              type: integer
              format: int64
              example: 1000
            next_marker:
              description: The marker for the start of the next page of results.
              type: string
              example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
              nullable: true
      title: AI sessions
      x-box-resource-id: ai_sessions_v2026.0
      x-box-tag: ai_sessions
    ClientError:
      description: A generic error.
      type: object
      properties:
        type:
          description: The value will always be `error`.
          type: string
          example: error
          enum:
            - error
          nullable: false
        status:
          description: The HTTP status of the response.
          type: integer
          format: int32
          example: 400
          nullable: false
        code:
          description: A Box-specific error code.
          type: string
          example: item_name_invalid
          enum:
            - created
            - accepted
            - no_content
            - redirect
            - not_modified
            - bad_request
            - unauthorized
            - forbidden
            - not_found
            - method_not_allowed
            - conflict
            - precondition_failed
            - too_many_requests
            - internal_server_error
            - unavailable
            - item_name_invalid
            - insufficient_scope
        message:
          description: A short message describing the error.
          type: string
          example: Method Not Allowed
          nullable: false
        context_info:
          description: >-
            A free-form object that contains additional context about the error.
            The possible fields are defined on a per-endpoint basis. `message`
            is only one example.
          type: object
          example:
            message: Something went wrong
          additionalProperties: {}
          nullable: true
        help_url:
          description: A URL that links to more information about why this error occurred.
          type: string
          example: >-
            https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
          nullable: false
        request_id:
          description: >-
            A unique identifier for this response, which can be used when
            contacting Box support.
          type: string
          example: abcdef123456
          nullable: false
      title: Client error
      x-box-resource-id: client_error_v2026.0
    AiSession:
      description: >-
        A standard representation of an AI session. An AI session holds the
        conversation state for a series of interactions with a Box AI agent. Its
        `id` is the A2A context identifier for that conversation.
      type: object
      properties:
        type:
          description: The value is always `ai_session`.
          type: string
          example: ai_session
          enum:
            - ai_session
        id:
          description: >-
            The unique identifier for the AI session. This is also the A2A
            `contextId` for the conversation. Treat the value as opaque.
          type: string
          example: '23489723'
        name:
          description: >-
            The display name of the AI session. Sessions created through the A2A
            API are named automatically. The value is `null` only when no name
            was recorded.
          type: string
          example: a2a-126bda90-ae78-4c81-b55f-c7ed9b678a8f
          nullable: true
        source:
          description: >-
            The origin of the AI session. Currently always `api`. New values may
            be added, so clients must tolerate values they do not recognize.
          type: string
          example: api
          enum:
            - api
        client_id:
          description: >-
            The OAuth client ID of the application that created the AI session,
            as shown in the Developer Console. The value is `null` if the
            application is not known.
          type: string
          example: ly1nj6n11vionaie65emwzk575hnnmrk
          nullable: true
        created_by:
          allOf:
            - $ref: '#/components/schemas/User--Base'
            - description: The user who created the AI session.
        updated_by:
          allOf:
            - $ref: '#/components/schemas/User--Base'
            - description: The user whose action last updated the AI session.
        created_at:
          description: The date and time when the AI session was created.
          type: string
          format: date-time
          example: '2026-09-01T10:30:00Z'
        updated_at:
          description: >-
            The date and time when the AI session was last updated. It advances
            on each turn of session activity, so it also serves as the most
            recently used ordering.
          type: string
          format: date-time
          example: '2026-09-18T14:22:00Z'
      required:
        - type
        - id
        - name
        - source
        - client_id
        - created_by
        - updated_by
        - created_at
        - updated_at
      title: AI session
      x-box-resource-id: ai_session_v2026.0
      x-box-tag: ai_sessions
    User--Base:
      description: >-
        A mini representation of a user, used when nested within another
        resource.
      type: object
      properties:
        id:
          description: The unique identifier for this user.
          type: string
          example: '11446498'
        type:
          description: The value will always be `user`.
          type: string
          example: user
          enum:
            - user
          nullable: false
      required:
        - type
        - id
      title: User (Base)
  securitySchemes:
    OAuth2Security:
      type: oauth2
      description: >-
        The access token received from the authorization server in the OAuth 2.0
        flow.
      flows:
        authorizationCode:
          authorizationUrl: https://account.box.com/api/oauth2/authorize
          tokenUrl: https://api.box.com/oauth2/token
          scopes:
            root_readonly: Read all files and folders stored in Box
            root_readwrite: Read and write all files and folders stored in Box
            manage_app_users: Provision and manage app users
            manage_managed_users: Provision and manage managed users
            manage_groups: Manage an enterprise's groups
            manage_webhook: Create webhooks programmatically through the API
            manage_enterprise_properties: Manage enterprise properties
            manage_data_retention: Manage data retention polices
            manage_legal_hold: Manage Legal Holds

````