Get assistant conversations

Export AI assistant conversation history from your documentation

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

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

Filtering

Filter conversations by date range using dateFrom and dateTo parameters.

Conversation data

Each conversation includes:

• query: The user’s question
• response: The assistant’s answer
• sources: Pages referenced in the response, with title and URL
• queryCategory: Classification of the query type (if available)

cURL

curl -X GET "https://api.mintlify.com/v1/analytics/{projectId}/assistant?dateFrom=2024-01-01&dateTo=2024-01-31&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

const projectId = 'your-project-id';
const dateFrom = '2024-01-01';
const dateTo = '2024-01-31';

const response = await fetch(
  `https://api.mintlify.com/v1/analytics/${projectId}/assistant?dateFrom=${dateFrom}&dateTo=${dateTo}&limit=100`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(`Retrieved ${data.conversations.length} conversations`);

// Paginate through results
let cursor = data.nextCursor;
while (data.hasMore && cursor) {
  const nextResponse = await fetch(
    `https://api.mintlify.com/v1/analytics/${projectId}/assistant?cursor=${cursor}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );
  const nextData = await nextResponse.json();
  console.log(`Retrieved ${nextData.conversations.length} more conversations`);
  cursor = nextData.nextCursor;
}

import requests

project_id = 'your-project-id'
date_from = '2024-01-01'
date_to = '2024-01-31'

response = requests.get(
    f"https://api.mintlify.com/v1/analytics/{project_id}/assistant",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    },
    params={
        "dateFrom": date_from,
        "dateTo": date_to,
        "limit": 100
    }
)

data = response.json()
print(f"Retrieved {len(data['conversations'])} conversations")

# Paginate through results
cursor = data.get('nextCursor')
while data['hasMore'] and cursor:
    next_response = requests.get(
        f"https://api.mintlify.com/v1/analytics/{project_id}/assistant",
        headers={
            "Authorization": "Bearer YOUR_API_KEY"
        },
        params={
            "cursor": cursor
        }
    )
    next_data = next_response.json()
    print(f"Retrieved {len(next_data['conversations'])} more conversations")
    cursor = next_data.get('nextCursor')

Endpoint

projectId · string · required

Your project ID. Can be copied from the API keys page in your dashboard.

Query Parameters

dateFrom · string

Date in ISO 8601 or YYYY-MM-DD format. Filter conversations that occurred on or after this date.

dateTo · string

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.

limit · number · default: "100"

Max results per page. Minimum: 1, Maximum: 1000.

cursor · string

Pagination cursor (ULID format) returned from a previous response.

Response

conversations · array

List of assistant conversations.

Show conversation object

id · string

Unique conversation identifier.

timestamp · string

ISO 8601 timestamp when the conversation occurred.

query · string

The user’s question to the assistant.

response · string

The assistant’s response.

sources · array

Documentation pages referenced in the response.

Show source object

title · string

Title of the referenced documentation page.

url · string

URL of the referenced documentation page.

queryCategory · string

Auto-assigned category grouping for the conversation, if applicable.

nextCursor · string

Cursor to retrieve the next page of results. Null if no more results.

hasMore · boolean

Whether additional results are available beyond this page.

Response

{
  "conversations": [
    {
      "id": "conv_123abc",
      "timestamp": "2024-01-15T10:30:00.000Z",
      "query": "How do I authenticate with the API?",
      "response": "To authenticate with the API, you need to include your API key in the Authorization header of your requests. You can generate an API key from your dashboard settings...",
      "sources": [
        {
          "title": "Authentication",
          "url": "https://docs.example.com/api-reference/authentication"
        },
        {
          "title": "API Keys",
          "url": "https://docs.example.com/api-reference/api-keys"
        }
      ],
      "queryCategory": "authentication"
    },
    {
      "id": "conv_456def",
      "timestamp": "2024-01-14T14:20:00.000Z",
      "query": "What programming languages are supported?",
      "response": "We provide SDKs and examples for JavaScript, Python, Ruby, Go, and PHP. You can find code examples in each language throughout our documentation...",
      "sources": [
        {
          "title": "SDKs",
          "url": "https://docs.example.com/sdks"
        },
        {
          "title": "Code Examples",
          "url": "https://docs.example.com/examples"
        }
      ],
      "queryCategory": "general"
    }
  ],
  "nextCursor": "01HQZX9K2MNBVCXZ7GQRST8WVY",
  "hasMore": true
}

Authentication

This endpoint requires an admin API key (prefixed with mint_). Generate one on the API keys page in your dashboard.