> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics API overview

> Use the analytics API to retrieve project-scoped session summaries, conversation messages, trace events, and LLM calls, with optional payload encryption.

Use the analytics API to retrieve data about the conversations in a project. You can list session summaries, conversation messages, agent trace events, and individual LLM calls with their token counts, latency, and cost.

## Prerequisites

* A Platform Key bound to the project you query. Send it in the `x-api-key` header.
* The `session:read` permission on the key for session summaries. The other endpoints need `analytics:read`.
* The project ID.
* For payload encryption, a Platform Key bound to exactly one project, with encryption turned on under **Settings > API Keys > Platform Keys** in Studio.

## Workflow and endpoint groups

The API returns four types of data. Each type has a GET article and a POST article that accepts an encrypted request body. Use the groups in this order to investigate sessions, or call any endpoint on its own.

| Sub-group | What to do | GET article | POST article |
| :- | :- | :- | :- |
| Sessions | List session summaries for a date range. Filter by source, channel, channel type, status, environment, or containment type. | [List session summaries](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-session-summaries) | [List session summaries using JWE payload](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-session-summaries-with-encrypted-payload) |
| Conversation messages | List the messages for the session IDs of interest. | [List conversation messages](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-conversation-messages) | [List conversation messages using JWE payload](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-conversation-messages-with-encrypted-payload) |
| Trace events | List the trace events for the same sessions to see how agents reached each result. | [List trace events](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-traces) | [List trace events using JWE payload](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-traces-with-encrypted-payload) |
| LLM calls | List LLM calls to review model, token, latency, and cost details for each call. Filter by end user. | [List LLM calls](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-llm-calls) | [List LLM calls using JWE payload](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-llm-calls-with-encrypted-payload) |

Use the session IDs from the sessions group to query messages and trace events.

## List of endpoints

All paths start with `/api/public/analytics/projects/{projectId}`.

| Use case | Help article | Purpose | Permission |
| :- | :- | :- | :- |
| Session summaries | [List session summaries](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-session-summaries) | Get one row per session with its source, channel, outcome, message count, token usage, and cost. Voice sessions include call quality metrics. | `session:read` |
| | [List session summaries using JWE payload](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-session-summaries-with-encrypted-payload) | Get the same data with the parameters in an encrypted request body. | `session:read` |
| Conversation messages | [List conversation messages](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-conversation-messages) | Get the messages exchanged in conversations, in time order, with the project's PII policy applied. | `analytics:read` |
| | [List conversation messages using JWE payload](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-conversation-messages-with-encrypted-payload) | Get the same data with the parameters in an encrypted request body. | `analytics:read` |
| Trace events | [List trace events](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-traces) | Get LLM calls, tool calls, agent decisions, and failures, grouped by trace. Optionally include HTTP tool response headers and workflow run steps. | `analytics:read` |
| | [List trace events using JWE payload](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-traces-with-encrypted-payload) | Get the same data with the parameters in an encrypted request body. | `analytics:read` |
| LLM calls | [List LLM calls](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-llm-calls) | Get one record per LLM call with its model, provider, token counts, latency, and cost. Filter by end user. | `analytics:read` |
| | [List LLM calls using JWE payload](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-llm-calls-with-encrypted-payload) | Get the same data with the parameters in an encrypted request body. | `analytics:read` |

## Behavior to know

* Different filters combine with AND. Multiple values in the same filter combine with OR.
* Session summaries and conversation messages accept either a date range (`fromDate` and `toDate`) or a list of `sessionIds`. Trace events and LLM calls need a date range.
* Trace events and LLM calls return key facts by default. Set `dataMode` to `full` to include the request and response content.
* Trace events can include the response headers of HTTP tool calls. Set `includeResponseHeaders` to `true` and `dataMode` to `full`. Trace events for workflow tool calls include the steps of the workflow run. See [Response headers](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-traces#response-headers) and [Workflow runs](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-traces#workflow-runs).
* A trace events response includes `meta.warnings` when part of the page can't be served in full. For example, `WORKFLOW_STEPS_UNAVAILABLE` means some workflow tool calls come back without their run steps. The events are still complete. See [Warnings](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-traces#warnings).
* Session summaries return only `user_initiated` sessions unless you set `source`. Earlier versions returned every source. Send `source=all` to include evaluation, debug, workflow, synthetic, and demo sessions. See [Source](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-session-summaries#source).
* The session summaries `channel` filter matches the exact channel ID and doesn't group channels into families. Use `channelType` to filter by family, such as `voice`. See [Channel and channel type](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-session-summaries#channel-and-channel-type).
* To find the sessions of an end user, filter by `channelUId`. Use the POST form so the identifier stays out of the URL. See [Filter by end user](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-session-summaries#filter-by-end-user).
* To find the LLM calls of an end user, filter by `channelUId`. Use the POST form so the identifier stays out of the URL. See [Filter by end user](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-llm-calls#filter-by-end-user).
* A sessions page can hold fewer rows than `limit` so the response stays within 1 MiB. Check `hasMore` instead of assuming a short page is the last one. For conversation messages, use `cursor` for paging.
* Every endpoint has a POST form on the same path. Send the same parameters as a flat JSON object. Use POST when the parameters must be encrypted, because a GET query string is never encrypted.
* Request encryption and response encryption are separate settings on the Platform Key. With request encryption on, send a JWE body. With response encryption on, every response after authentication is a JWE, except `401`.
* Exceeding the tenant request rate limit returns `429`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.