Query Analytics via API

6 min read

All the requests work as jobs, they can be requested then they are in the background generated and can be retrieved after through a download link in CSV format.

The contents of the analytics are explained here: Analytics

The analytics are also availble via the Unique SDK v2026.20

Access Token & URL

You can see here how to get an access token and the URL: How to get a Token for the GraphQL APIs

Refer to Multitenant Region URLs to find the correct base URL for your deployment.

About these APIs

Overview

All analytics requests are async jobs. You trigger a report request, receive a job ID, poll until the state is DONE, then download the result as a CSV file.

Base URL pattern:

https://gateway.<cluster>.unique.app
https://gateway.<your_custom_url>

Authentication: All endpoints require a Bearer token in the Authorization header. See How to get a Token for our APIs in the Unique AI Documentation space.

Job Lifecycle

Start the job — call the relevant endpoint with startDate & endDate
Poll analyticsOrders (GraphQL) every ≥10 s until state = "DONE"
Download — GET /chat/analytics/analytics-scheduler/download/<ORDER_ID> with Accept: text/csv
Delete — call analyticsOrderDelete mutation to clean up completed jobs

Date Range

Default when no dates provided: last 1 day
Default UI range: last 180 days
Maximum allowed range: 365 days
Detailed Chat Interaction max: 14 days (every chat interaction)

Report Types & Data Points

1. Chat Interactions (CHAT_INTERACTION)

POST /public/chat/analytics/orders
{
  "type": "CHAT_INTERACTION",
  "startDate": "YYYY-MM-DD",
  "endDate": "YYYY-MM-DD",
  "assistantId": "<space_id>"
}

The assistantId is an optional parameter.
Use to evaluate: which assistant is used most, number of interactions per user per day, device breakdown of usage.
Required role: chat.feedback.read or chat.data.admin

CSV Column	Type	Description	Notes
Email	string	Email of the user who interacted	Anonymized if `ANONYMIZED_CHAT_INTERACTIONS_EXPORT=true`
Date	date	Date of interaction	Format: dd.MM.yyyy
Assistant	string	Name of the assistant/space used
Count	integer	Total interactions (Q&A pairs) on that date
DesktopCount	integer	Interactions from desktop devices	⚠ Not in previous documentation
SmartphoneCount	integer	Interactions from smartphone devices	⚠ Not in previous documentation
TabletCount	integer	Interactions from tablet devices	⚠ Not in previous documentation
OtherDeviceCount	integer	Interactions from other/unknown devices	⚠ Not in previous documentation

2. Active Users (ACTIVE_USER)

POST /public/chat/analytics/orders
{
  "type": "ACTIVE_USER",
  "startDate": "YYYY-MM-DD",
  "endDate": "YYYY-MM-DD",
  "assistantId": "<space_id>"
}

The assistantId is an optional parameter.
Use to evaluate: DAU / WAU / MAU trends on the platform.
Required role: chat.feedback.read or chat.data.admin

CSV Column	Type	Description	Notes
Period	string	Aggregation window: day / week / month
Date	date	Date of the period	Weekly = end of 7-day window, e.g. week 10.02.24 = 04.02–10.02
Value	integer	Count of unique users who had ≥1 interaction in the period

3. Reference Statistics (REFERENCE_STAT)

POST /public/chat/analytics/orders
{
  "type": "REFERENCE_STAT",
  "startDate": "YYYY-MM-DD",
  "endDate": "YYYY-MM-DD",
  "assistantId": "<space_id>"
}

The assistantId is an optional parameter.
Use to evaluate: which documents are referenced most, who uploaded them, and to which scope.
Required role: chat.feedback.read or chat.data.admin

CSV Column	Type	Description	Notes
File Uploaded Date	date	Date the file was ingested
File Name	string	Document name as shown in Knowledge Center
File Uploader	string	Email of the uploader	Generic user ID for SharePoint sources
Source	string	Origin of the document	`UNIQUE_BLOB_STORAGE` or `MICROSOFT_365_SHAREPOINT`
Reference Count	integer	Number of times the doc was referenced in answers
Scope	string	Knowledge base folder/scope the file belongs to

4. Detailed Chat Interactions (CHAT_INTERACTION_DETAILED)

POST /public/chat/analytics/orders
{
  "type": "CHAT_INTERACTION_DETAILED",
  "startDate": "YYYY-MM-DD",
  "endDate": "YYYY-MM-DD",
  "assistantId": "<space_id>"
}

The assistantId is an optional parameter.
Use to evaluate: frequently asked questions, missing knowledge gaps, per-conversation device usage. Not available on multi-tenant instances. Date range must not exceed 14 days.
Required role: chat.feedback.read — Message + Answer columns require chat.data.admin

CSV Column	Type	Description	Notes
Username	string	Display name of the user	"Unknown" when anonymized
Timestamp	datetime	Date & time the message was sent	ISO 8601
Space	string	Assistant/space used for this message
Chat ID	string	Groups all messages belonging to the same conversation
Device Category	string	Device type used	desktop / smartphone / tablet / other
Message	string	The user's message text	Only returned with `chat.data.admin` role
Answer	string	Unique AI's response text	Only returned with `chat.data.admin` role

5. Ingestion Report (INGESTION_STAT) 🆕

POST /public/chat/analytics/orders
{
  "type": "INGESTION_STAT",
  "startDate": "YYYY-MM-DD",
  "endDate": "YYYY-MM-DD",
  "assistantId": "<space_id>"
}

The assistantId is an optional parameter.
Use to evaluate: how many files and pages each user has ingested in a given period.
Required role: chat.feedback.read or chat.data.admin

CSV Column	Type	Description
UserId	string	Unique identifier of the user
Email	string	Email address of the user who ingested content
ContentCount	integer	Number of documents/files ingested
PageCount	integer	Total pages processed across all ingested content

6. Product Metrics (PRODUCT_METRICS) 🆕

POST /public/chat/analytics/orders
{
  "type": "PRODUCT_METRICS",
  "startDate": "YYYY-MM-DD",
  "endDate": "YYYY-MM-DD",
  "assistantId": "<space_id>"
}

The assistantId is an optional parameter.
Use to evaluate: DAU/WAU/MAU and granular per-feature engagement across Chat, RAG, and Agentic Table. All metrics are tracked per unique user per day.
Required role: chat.feedback.read

CSV Column	Type	Description
S/N	integer	Row serial number
Metric Key	string	Identifier for the metric (see table below)
Metric Value	integer	Value of the metric for the period
Partition Timestamp	datetime	Time period this metric belongs to

Available Metric Keys:

Metric Key	Category	Triggered When
`space_interaction`	Chat	User opens a new space/chat
`context_window_interaction`	Chat	User opens the context window
`select_files_to_chat`	Chat	User selects a file to chat with
`kb_visit`	RAG	User visits the knowledge base
`kb_document_upload`	RAG	User uploads a file to the knowledge base
`kb_scope_created`	RAG	User creates a new folder/scope
`kb_document_search`	RAG	User searches a file in the knowledge base
`agentic_table_sheet_creation`	Agentic Table	User creates a new sheet
`agentic_table_library_sheet_creation`	Agentic Table	New answer library sheet is created
`agentic_table_sheet_deletion`	Agentic Table	User deletes a sheet
`agentic_table_sheet_completion`	Agentic Table	User marks a non-library sheet as completed
`agentic_table_library_sheet_completion`	Agentic Table	User marks a library sheet as completed
`agentic_table_cell_update`	Agentic Table	User edits or adds a cell
`agentic_table_metadata_added_existing_sheet`	Agentic Table	Sources/questions added to existing sheet
`agentic_table_metadata_added_new_sheet`	Agentic Table	Sources/questions added during new sheet creation

MCP, Tools, and MCP-server Usage are also included in the metric keys but cannot all be listed here in this table as the keys would depend on what tools are available. An example metric key for Internal Search tool usage is message:tools:usage:InternalSearch while for Outlook MCP server usage it looks like mcp:server:tool:usage:outlook.mcp.unique.app

7. Model Usage (MODEL_USAGE) 🆕

POST /public/chat/analytics/orders
{
  "type": "MODEL_USAGE",
  "startDate": "YYYY-MM-DD",
  "endDate": "YYYY-MM-DD",
  "assistantId": "<space_id>"
}

The assistantId is an optional parameter.
Use to evaluate: LLM consumption per user, assistant, and conversation — including cost and token counts.
Required role: chat.feedback.read and chat.data.admin

CSV Column	Type	Description	Notes
S/N	integer	Row serial number
User ID	string	Identifier of the user	May be anonymized per company config
Assistant ID	string	Identifier of the assistant/space
Chat ID	string	Identifier of the conversation
App ID	string	Application identifier
Language Model	string	Name/ID of the LLM used	e.g. gpt-4o, claude-3-5-sonnet
Spent	decimal	Cost/spend amount for this call	Currency depends on deployment config
Input Tokens	integer	Token count for the input/prompt
Completion Tokens	integer	Token count for the completion/response
Timestamp	datetime	Date & time of the model call	ISO 8601

8. Net Promoter Score (NPS) 🆕

POST /public/chat/analytics/orders
{
  "type": "NPS",
  "startDate": "YYYY-MM-DD",
  "endDate": "YYYY-MM-DD",
  "assistantId": "<space_id>"
}

The assistantId is an optional parameter.
Use to evaluate: user satisfaction via in-product NPS surveys.
Required role: chat.feedback.read and chat.data.admin

CSV Column	Type	Description	Notes
Score	integer	NPS score submitted by the user	Range: 0–10
Feedback	string	Optional free-text comment	May be empty
Created By	string	Email of the user who submitted
Created At	datetime	When the NPS response was submitted	ISO 8601

Privacy & Anonymization

User email addresses in analytics exports can be anonymized via environment variables on the deployment:

Setting	Value	Effect
`ANONYMIZED_CHAT_INTERACTIONS_EXPORT`	`true`	Randomizes email identifiers on every export (identifiers differ across exports)
`ANONYMIZED_CHAT_INTERACTIONS_EXPORT_TYPE`	`idempotent`	Stable pseudonyms — same user always maps to the same anonymized identifier

Tip: Use idempotent mode when correlating data across multiple exports is required (e.g. PowerBI dashboards).

Role Requirements Summary

Report	Minimum Role	For Full Data (incl. message/prompt content)
Chat Interactions	`chat.feedback.read`	—
Active Users	`chat.feedback.read`	—
Reference Statistics	`chat.feedback.read`	—
Detailed Chat Interactions	`chat.feedback.read`	`chat.data.admin` (Message + Answer columns)
Ingestion Stat	`chat.feedback.read`	—
Product Metrics	`chat.feedback.read`	—
Model Usage	`chat.feedback.read`	—
NPS	`chat.feedback.read`	—
User Chat Export	`chat.feedback.read`	`chat.data.admin` (Prompt column)

GraphQL Reference

Fetch Orders

GET /public/chat/analytics/orders?skip=<skipOrders>&take=<takeOrders>

graphql

[{
  "id": "analyticOrder_xkixrccfj0dbd4qczuv2b7tv",
  "object": "analytics-order",
  "type": "ACTIVE_USER",
  "state": "DONE",       # PENDING | PROCESSING | DONE | FAILED
  "configuration": {
    "endDate": "2025-02-01",
    "startDate": "2026-01-01",
    "hidePromptsData": true
  },
  "createdAt": "2026-05-06T09:17:38.105Z",
  "updatedAt": "2026-05-06T09:17:38.595Z",
  "stateUpdatedAt": "2026-05-06T09:17:38.594Z"
}]

Fetch one Order

GET /public/chat/analytics/orders/{orderId}

graphql

{
  "id": "analyticOrder_xkixrccfj0dbd4qczuv2b7tv",
  "object": "analytics-order",
  "type": "ACTIVE_USER",
  "state": "DONE",       # PENDING | PROCESSING | DONE | FAILED
  "configuration": {
    "endDate": "2025-02-01",
    "startDate": "2026-01-01",
    "hidePromptsData": true
  },
  "createdAt": "2026-05-06T09:17:38.105Z",
  "updatedAt": "2026-05-06T09:17:38.595Z",
  "stateUpdatedAt": "2026-05-06T09:17:38.594Z"
}

Download a Completed Job

GET /public/chat/analytics/orders/{orderId}/download

Delete a Completed Job

DELETE /public/chat/analytics/orders/{orderId}