Skip to main content
Mintlify

Search documentation

Type to search this documentation.

On this pageOverview

Get assistant conversations

Returns paginated AI assistant conversation history

Authenticate with an admin API key.

Usage

Section titled “Usage”

Use this endpoint to export AI assistant conversation history from your documentation. Each conversation includes the user query, assistant response, sources cited, resolution status, and query category.

Paginate through results using the cursor parameter returned in the response. Continue fetching while hasMore is true.

Filtering

Section titled “Filtering”

Filter conversations by date range using dateFrom and dateTo parameters.

Conversation data

Section titled “Conversation data”

Each row represents one user turn in a conversation. A conversation with multiple back-and-forth messages produces multiple rows that share a conversationId.

Each row includes:

  • query: The user's question.
  • response: The assistant's answer. For clarifying-question turns, this is the follow-up question the assistant asked the user.
  • responseType: Either answer or clarifying_question. clarifying_question means the assistant asked the user a follow-up question instead of answering. Defaults to answer when not present.
  • sources: Pages referenced in the response, with title and URL.
  • resolutionStatus: Whether the assistant successfully answered this turn. Either answered or unanswered. Computed per row, so a single conversation can contain both statuses. Use this field to track and analyze documentation gaps surfaced by user questions the assistant could not resolve.
  • timestamp: When the user sent the message that started this turn. Rows in the same conversation have different timestamps.
  • queryCategory: Classification of the query type, if available.
  • feedback: The user's thumbs rating on the assistant's response. Either positive, negative, or null if the user did not rate the response.
  • pageUrl: Full URL of the documentation page where the conversation started, or null if no page path is available. Use this field to attribute conversations to a specific page.

Rate limits

Section titled “Rate limits”

This endpoint allows 100 requests per organization per hour. All analytics endpoints share this limit.

OpenAPI

Section titled “OpenAPI”
analytics.openapi.json
openapi: 3.1.0
info:
  title: Mintlify Analytics Export API
  version: 1.0.0
  description: API for exporting documentation analytics data
servers:
  - url: https://api.mintlify.com
    description: Production
security: []
paths:
  /v1/analytics/{projectId}/assistant:
    get:
      tags:
        - Analytics
      summary: Get assistant conversations
      description: |-
        Returns paginated AI assistant conversation history

        Authenticate with an admin API key.
      parameters:
        - $ref: '#/components/parameters/projectId'
        - schema:
            type: string
            description: Date in ISO 8601 or YYYY-MM-DD format
            example: '2024-01-01'
          required: false
          name: dateFrom
          in: query
        - schema:
            type: string
            description: >-
              Date in ISO 8601 or YYYY-MM-DD format. `dateTo` is an exclusive
              upper limit. Results include dates before, but not on, the
              specified date.
            example: '2024-01-01'
          required: false
          name: dateTo
          in: query
        - schema:
            type: number
            minimum: 1
            maximum: 1000
            default: 100
            description: Max results per page
          required: false
          name: limit
          in: query
        - schema:
            type: string
            format: ulid
            description: Pagination cursor (ULID format)
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Conversation data with pagination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantConversationsResponse'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsErrorResponse'
      security:
        - bearerAuth: []
components:
  parameters:
    projectId:
      schema:
        $ref: '#/components/schemas/projectId'
      required: true
      name: projectId
      in: path
  schemas:
    AssistantConversationsResponse:
      type: object
      properties:
        conversations:
          type: array
          description: List of assistant conversations.
          items:
            type: object
            properties:
              id:
                type: string
                description: Unique conversation identifier.
              timestamp:
                type: string
                description: Timestamp of the user message that started this turn.
              query:
                type: string
                description: The user's question to the assistant.
              response:
                type: string
                description: >-
                  The assistant's response. For clarifying-question turns, this
                  is the question the assistant asked the user.
              responseType:
                type: string
                enum:
                  - answer
                  - clarifying_question
                description: >-
                  Type of response returned to the user. `answer` is a final
                  answer. `clarifying_question` means the assistant asked the
                  user a follow-up question instead of answering. Defaults to
                  `answer` when not present.
              sources:
                type: array
                description: Documentation pages referenced in the response.
                items:
                  type: object
                  properties:
                    title:
                      type: string
                      description: Title of the referenced documentation page.
                    url:
                      type: string
                      description: URL of the referenced documentation page.
                  required:
                    - title
                    - url
              resolutionStatus:
                type: string
                enum:
                  - answered
                  - unanswered
                description: >-
                  Whether the assistant successfully answered this turn.
                  Computed per row: `unanswered` when the assistant marked the
                  question as not covered by the available documentation,
                  otherwise `answered`.
              queryCategory:
                type:
                  - string
                  - 'null'
                description: >-
                  Auto-assigned category grouping for the conversation, if
                  applicable.
              feedback:
                type:
                  - string
                  - 'null'
                enum:
                  - positive
                  - negative
                  - null
                description: >-
                  The user's thumbs rating on the assistant's response.
                  `positive` for thumbs up, `negative` for thumbs down, or
                  `null` if the user did not rate the response.
              pageUrl:
                type:
                  - string
                  - 'null'
                description: >-
                  Full URL of the documentation page where the conversation
                  started. Null if no page path was captured.
            required:
              - id
              - timestamp
              - query
              - response
              - sources
              - resolutionStatus
              - queryCategory
              - feedback
              - pageUrl
        nextCursor:
          type:
            - string
            - 'null'
          description: >-
            Cursor to retrieve the next page of results. Null if no more
            results.
        hasMore:
          type: boolean
          description: Whether additional results are available beyond this page.
      required:
        - conversations
        - nextCursor
        - hasMore
    AnalyticsErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong.
        details:
          type: array
          description: Additional details about the error.
          items:
            type: object
            properties:
              message:
                type: string
                description: Description of a specific validation or processing error.
            required:
              - message
      required:
        - error
    projectId:
      type: string
      description: >-
        Your project ID. Can be copied from the [API
        keys](https://app.mintlify.com/settings/organization/api-keys) page in
        your dashboard.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        The Authorization header expects a Bearer token. Use an admin API key.
        This is a server-side secret key. Generate one on the [API keys
        page](https://app.mintlify.com/settings/organization/api-keys) in your
        dashboard.
Section titled “Related topics”
Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu