# Query Analytics via API

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](https://docs.unique.ai/administrators/insights-measurement/analytics-interface/analytics)

The analytics are also available 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](https://docs.unique.ai/developers/software-development-kit-sdk/apis-graphql-internal-apis-for-admins/how-to-get-a-token-for-the-graphql-apis)

Refer to [Multitenant Region URLs](https://docs.unique.ai/it-operators/installing-and-upgrading-unique/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
1. **Start the job** — call the relevant endpoint with `startDate` & `endDate`
2. **Poll** `analyticsOrders` (GraphQL) every ≥10 s until `state = "DONE"`
3. **Download** — `GET /chat/analytics/analytics-scheduler/download/<ORDER_ID>` with `Accept: text/csv`
4. **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>"
}
```
**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>"
}
```
**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>"
}
```
**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>"
}
```
**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>"
}
```
**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 | Notes |
| --- | --- | --- | --- |
| 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>"
}
```
**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 |

### 7. Model Usage (MODEL_USAGE)
```
POST /public/chat/analytics/orders
{
  "type": "MODEL_USAGE",
  "startDate": "YYYY-MM-DD",
  "endDate": "YYYY-MM-DD",
  "assistantId": "<space_id>"
}
```
**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>"
}
```
**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}`