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

# List chat threads

**🔒 Admin only.** Requires administrator privileges — the authenticated principal (API key, embed JWT, or any bearer token) must belong to a user with the admin role.

Every user's AI chat threads in the deployment, most recently updated first, for analyzing how people use the agent. Filters combine with AND; a filter given several values matches any of them.

Set `includeTurns=true` to get each thread's turns in the same response. A turn is one prompt and everything the agent did to answer it: the final answer, the tools it called, and each query it ran with its SQL, status, row count and any thumbs-up/down feedback. Query result rows are never included. A prompt, answer or SQL longer than 20,000 characters, or an error longer than 2,000, is cut and ends in `…`. A page holds up to 200 threads, or 50 with turns; a larger `first` is lowered to that.

For an incremental export, keep the newest `updatedAt` you have seen and pass it as `updatedAfter` next time.

Chat history export is in preview: when it is not enabled for the account, `404` is returned.


## OpenAPI

````yaml /api-reference/api.yaml get /api/v1/deployments/{deploymentId}/chat-history/threads
openapi: 3.1.0
info:
  title: Cube Platform API
  version: 1.0.0
  description: >-
    Programmatically manage Cube: deployments and everything scoped to them

    (environments, folders, reports, workbooks, notifications, workspace, and
    agents),

    plus account-level users, groups, policies, embedding, and AI settings.
    Data-model

    authoring, dev mode, branches, and uploads live under /build/api/v1 — same
    host and

    token, routed to the build pods.
servers:
  - url: https://{tenant}.cubecloud.dev
    description: Your tenant host. Replace the whole host if you use a custom domain.
    variables:
      tenant:
        default: your-tenant
        description: Your Cube tenant subdomain
security:
  - bearerAuth: []
tags:
  - name: Deployments
  - name: Deployment Creation
  - name: Environments
  - name: Env Variables
  - name: Regions
  - name: Data Model
  - name: Data Model Uploads
  - name: GitHub
  - name: GitHub Connection
  - name: dbt Sync
  - name: Databricks Metric View Publication
  - name: Databricks Metric View Integration
  - name: Snowflake Semantic View Sync
  - name: Folders
  - name: Reports
  - name: External Documents
  - name: Workbooks
  - name: Workbook Promotions
  - name: Dashboard Exports
  - name: Notifications
  - name: Scheduled Tasks
  - name: Workspace
  - name: Agents
  - name: Users
  - name: Users Admin
  - name: API Keys
  - name: User Attributes
  - name: User Attribute Values
  - name: Tenant Settings
  - name: OAuth Integrations
  - name: User OAuth Tokens
  - name: OIDC Token Configs
  - name: App Theme
  - name: Embed
  - name: Embed Tenants
  - name: Dashboard Embed Access
  - name: Usage Analytics
  - name: OpenAPI Spec
  - name: Chat History
  - name: Ossie Conversion
  - name: Report Deliveries
paths:
  /api/v1/deployments/{deploymentId}/chat-history/threads:
    get:
      tags:
        - Chat History
      summary: List chat threads
      operationId: listChatHistoryThreads
      parameters:
        - in: path
          name: deploymentId
          required: true
          schema:
            type: integer
        - in: query
          name: createdAfter
          schema:
            description: >-
              Only threads whose `createdAt` is at or after this ISO 8601 date
              or date-time.
            oneOf:
              - pattern: >-
                  ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$
                type: string
              - type: 'null'
        - in: query
          name: createdBefore
          schema:
            description: >-
              Only threads whose `createdAt` is at or before this ISO 8601
              date-time. A date alone (`2026-10-01`) includes that whole day,
              UTC.
            oneOf:
              - pattern: >-
                  ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$
                type: string
              - type: 'null'
        - in: query
          name: updatedAfter
          schema:
            description: >-
              Only threads whose `updatedAt` is at or after this ISO 8601 date
              or date-time. A thread is updated by every new turn, so this is
              the filter for incremental exports.
            oneOf:
              - pattern: >-
                  ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$
                type: string
              - type: 'null'
        - in: query
          name: updatedBefore
          schema:
            description: >-
              Only threads whose `updatedAt` is at or before this ISO 8601
              date-time. A date alone (`2026-10-01`) includes that whole day,
              UTC.
            oneOf:
              - pattern: >-
                  ^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$
                type: string
              - type: 'null'
        - in: query
          name: userId
          schema:
            description: >-
              Cube user ids. Repeat the parameter to match any of several
              values, up to 100.
            oneOf:
              - items:
                  type: integer
                type: array
                maxItems: 100
              - type: 'null'
        - in: query
          name: userEmail
          schema:
            description: >-
              User emails, matched case-insensitively against Cube users and
              against the email an embedded user signed in with. Repeat the
              parameter to match any of several values, up to 100.
            oneOf:
              - items:
                  type: string
                type: array
                maxItems: 100
              - type: 'null'
        - in: query
          name: externalUserId
          schema:
            description: >-
              External ids of embedded-analytics users, as your application
              passed them. Repeat the parameter to match any of several values,
              up to 100.
            oneOf:
              - items:
                  type: string
                type: array
                maxItems: 100
              - type: 'null'
        - in: query
          name: userType
          schema:
            description: >-
              `internal` for Cube users, `external` for embedded-analytics
              users. Combines with the user filters above, which match any of
              their values.
            oneOf:
              - $ref: '#/components/schemas/ChatHistoryThreadsQueryUserType'
              - type: 'null'
        - in: query
          name: source
          schema:
            description: >-
              Where the thread was started: `web` (the Cube app or embedded
              analytics), `api` (the Chat API), `mcp`, `slack` or `scheduled` (a
              scheduled task). Repeat the parameter to match any of several
              values, up to 100.
            oneOf:
              - items:
                  enum:
                    - web
                    - api
                    - mcp
                    - slack
                    - scheduled
                  type: string
                type: array
                maxItems: 100
              - type: 'null'
        - in: query
          name: initialContext
          schema:
            description: >-
              The surface inside the app the thread began on. Repeat the
              parameter to match any of several values, up to 100.
            oneOf:
              - items:
                  type: string
                  enum:
                    - chat
                    - workbook
                    - model
                    - dashboard
                    - external
                    - mcp
                    - ai-widget
                    - onboarding
                    - explore
                    - connection_setup
                    - slack_dm
                    - published-dashboard
                    - sheets
                type: array
                maxItems: 100
              - type: 'null'
        - in: query
          name: agentId
          schema:
            description: >-
              Agent ids; `-1` selects the Auto agent. Repeat the parameter to
              match any of several values, up to 100.
            oneOf:
              - items:
                  type: integer
                type: array
                maxItems: 100
              - type: 'null'
        - in: query
          name: search
          schema:
            description: Case-insensitive match on the thread title or its chat id.
            oneOf:
              - type: string
              - type: 'null'
        - in: query
          name: sortBy
          schema:
            description: Defaults to `updatedAt`.
            oneOf:
              - $ref: '#/components/schemas/ChatHistoryThreadsQuerySortBy'
              - type: 'null'
        - in: query
          name: sortOrder
          schema:
            description: Defaults to `desc`.
            oneOf:
              - $ref: '#/components/schemas/ChatHistoryThreadsQuerySortOrder'
              - type: 'null'
        - in: query
          name: includeTurns
          schema:
            description: >-
              Return every thread with its turns. Pages then default to 20
              threads and hold at most 50.
            oneOf:
              - type: boolean
              - type: 'null'
        - in: query
          name: after
          schema:
            type: string
        - in: query
          name: first
          schema:
            minimum: 1
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatHistoryThreadListResponse'
          description: ''
components:
  schemas:
    ChatHistoryThreadsQueryUserType:
      enum:
        - internal
        - external
      type: string
    ChatHistoryThreadsQuerySortBy:
      enum:
        - createdAt
        - updatedAt
      type: string
    ChatHistoryThreadsQuerySortOrder:
      enum:
        - asc
        - desc
      type: string
    ChatHistoryThreadListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ChatHistoryThread'
          type: array
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
      required:
        - items
        - pageInfo
      type: object
    ChatHistoryThread:
      properties:
        agentId:
          description: Null for the Auto agent.
          oneOf:
            - type: integer
            - type: 'null'
        chatId:
          description: The thread id, as used in chat URLs and the Chat API.
          type: string
        createdAt:
          type: string
        initialContext:
          description: >-
            The surface inside the app the thread began on; null when it was not
            recorded.
          oneOf:
            - type: string
            - type: 'null'
        source:
          description: >-
            Where the thread was started; null for a source this API does not
            name.
          oneOf:
            - $ref: '#/components/schemas/ChatHistoryThreadSource'
            - type: 'null'
        title:
          oneOf:
            - type: string
            - type: 'null'
        turns:
          description: >-
            Oldest first. Present on a single thread, and on a list with
            `includeTurns=true`.
          oneOf:
            - items:
                $ref: '#/components/schemas/ChatHistoryTurn'
              type: array
            - type: 'null'
        updatedAt:
          description: When the thread last changed, normally its latest turn.
          type: string
        user:
          $ref: '#/components/schemas/ChatHistoryUser'
      required:
        - chatId
        - user
        - createdAt
        - updatedAt
      type: object
    PageInfo:
      properties:
        endCursor:
          oneOf:
            - type: string
            - type: 'null'
        hasNextPage:
          type: boolean
        hasPreviousPage:
          type: boolean
        startCursor:
          oneOf:
            - type: string
            - type: 'null'
      required:
        - hasNextPage
        - hasPreviousPage
      type: object
    ChatHistoryThreadSource:
      enum:
        - web
        - api
        - mcp
        - slack
        - scheduled
      type: string
    ChatHistoryTurn:
      properties:
        endedAt:
          description: >-
            The agent's last write in the turn. Null for turns recorded before
            Cube stored turn times.
          oneOf:
            - type: string
            - type: 'null'
        files:
          description: Names of files the user attached. Their content is never included.
          items:
            type: string
          type: array
        finalAnswer:
          description: >-
            The agent's last text reply in the turn; null when it answered only
            with a chart.
          oneOf:
            - type: string
            - type: 'null'
        index:
          description: Position in the thread, from 0.
          type: integer
        messageId:
          description: The id of the user message that opened the turn.
          type: string
        prompt:
          description: What the user asked, as they typed it.
          type: string
        queries:
          items:
            $ref: '#/components/schemas/ChatHistoryQuery'
          type: array
        startedAt:
          description: >-
            When the user sent the prompt. Null for turns recorded before Cube
            stored turn times.
          oneOf:
            - type: string
            - type: 'null'
        tools:
          description: Every tool the agent called in the turn, in first-call order.
          items:
            type: string
          type: array
      required:
        - index
        - messageId
        - prompt
        - files
        - tools
        - queries
      type: object
    ChatHistoryUser:
      properties:
        email:
          description: >-
            Null when the Cube user was deleted, or the embedded user had no
            email.
          oneOf:
            - type: string
            - type: 'null'
        externalId:
          description: Embedded users only.
          oneOf:
            - type: string
            - type: 'null'
        id:
          description: >-
            For a Cube user, their user id. For an embedded user, an id in a
            separate number space: identify them by `externalId`.
          type: integer
        name:
          description: Cube users only.
          oneOf:
            - type: string
            - type: 'null'
        type:
          $ref: '#/components/schemas/ChatHistoryUserType'
      required:
        - id
        - type
      type: object
    ChatHistoryQuery:
      properties:
        dataSource:
          description: The data source a `runSql` query ran on.
          oneOf:
            - type: string
            - type: 'null'
        error:
          oneOf:
            - type: string
            - type: 'null'
        feedback:
          description: The latest thumbs up or down on this query, if any.
          oneOf:
            - $ref: '#/components/schemas/ChatHistoryQueryFeedback'
            - type: 'null'
        messageId:
          description: The tool-call message id.
          type: string
        rowCount:
          description: Rows the query returned. The rows themselves are never included.
          oneOf:
            - type: integer
            - type: 'null'
        sql:
          description: The SQL the agent generated.
          oneOf:
            - type: string
            - type: 'null'
        status:
          $ref: '#/components/schemas/ChatHistoryQueryStatus'
          description: >-
            `incomplete` when the query never returned: the turn was stopped or
            failed.
        title:
          oneOf:
            - type: string
            - type: 'null'
        tool:
          description: >-
            `cubeSqlApi` for a query against the semantic layer, `runSql` for
            one against a warehouse data source.
          type: string
      required:
        - messageId
        - tool
        - status
      type: object
    ChatHistoryUserType:
      enum:
        - internal
        - external
      type: string
    ChatHistoryQueryFeedback:
      properties:
        createdAt:
          type: string
        isPositive:
          type: boolean
        userId:
          description: Who rated the query.
          oneOf:
            - type: integer
            - type: 'null'
      required:
        - isPositive
        - createdAt
      type: object
    ChatHistoryQueryStatus:
      enum:
        - success
        - error
        - incomplete
      type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Token authentication. Send `Authorization: Bearer <YOUR_TOKEN>`.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.