Get top questions

GET

/api/v1/visitors/grouped_questions

The questions visitors ask most often, the ones the AI most often could not answer, and the ones most often downvoted. Similar questions are clustered, so each entry represents a group of near-identical phrasings, with message showing the most common one. These are the lists on the dashboard’s performance page.

Notes

• All three lists come back in one results array. Split them on type: commonlyAskedQuestions, commonlyUnansweredQuestions or commonlyDownvotedQuestions
• Each list holds up to 100 entries, sorted by frequency, highest first
• startTime and endTime are Unix timestamps in milliseconds, not YYYY-MM-DD days, and both are inclusive. Leave them out to cover the whole history
• conversations lists up to 10 of the most recent conversations in the range the question was asked in, newest first. Conversations deleted since are left out
• Computed live rather than read from a query cache, so there is no status or forceRefresh

Parameters

Header Parameters

x-api-key

required

string

Your API key from account settings.

x-user-email

required

string

The email address of your user.

x-account-id

required

string

The ID of your account. You can find this in the account settings.

x-website-id

required

string

The ID of the workspace you want to use.

Query Parameters

startTime

integer format: int64

Start of the range as a Unix timestamp in milliseconds, inclusive. Defaults to the beginning of the history.

endTime

integer format: int64

End of the range as a Unix timestamp in milliseconds, inclusive. Defaults to now.

personalizationId

string

Restrict the lists to one channel. Leave it out to cover every channel. all-ai-assistants covers every AI assistant on your website and excludes API traffic. API channels include api, api-summarization, api-team-assistant, api-team-assistant-summarization, api-dashboard, api-report, api-ticket-analysis and api-resource-optimization. Use comma-separated values to combine channels.

segmentId

string

Restrict the lists to one segment. Leave it out for the lists across all segments.

Responses

200

The three question lists, combined into one array.

object

results

Array<object>

object

id

Identifies the question group.

integer

message

The most common phrasing in the group.

string

frequency

How often a question in the group was asked in the range.

integer

type

Which list the entry belongs to.

string

Allowed values: commonlyAskedQuestions commonlyUnansweredQuestions commonlyDownvotedQuestions

conversations

Up to 10 of the most recent conversations in the range the question was asked in, newest first.

Array<object>

object

conversationId

string

sessionId

string

nullable

title

Title from the conversation analysis, when the conversation has been analyzed.

string

nullable

createdAt

Unix timestamp (ms) when the conversation started.

number

nullable

Example

{
  "results": [
    {
      "id": 48213,
      "message": "How do I reset my password?",
      "frequency": 142,
      "type": "commonlyAskedQuestions",
      "conversations": [
        {
          "conversationId": "7f3c2a90-1b4e-4d2a-9c61-2f0e8b7a5d13",
          "sessionId": "0b9d4e6f-8a21-4c7e-b3f5-6e2d1a9c8b47",
          "title": "Password reset",
          "createdAt": 1759831200000
        }
      ]
    },
    {
      "id": 51877,
      "message": "Can I pay by invoice?",
      "frequency": 37,
      "type": "commonlyUnansweredQuestions",
      "conversations": []
    }
  ]
}

400

The workspace could not be determined from the headers.

401

Unauthorized - invalid API key.