REST API: analytics and activity

Analytics endpoints return dashboard data on statistics, daily trends, sentiment, feedback, confidence, retrieval modes, geography, low-confidence responses, and escalations. These are reporting endpoints. The generated reference documents their filters and date rules.

A date-only dateTo value includes the full UTC day, through its end. Timestamp inputs need an explicit time zone. A reversed date range causes a validation error.

Exports run as an asynchronous process. You create an export, save its ID, and poll that resource at a reasonable interval. Activity sessions use separate pagination and message-detail routes. The analytics cursor pattern does not apply to them.

POST /analytics/exports returns 400 INVALID_INPUT for an invalid date range, 404 AGENT_NOT_FOUND for an unavailable agent, and 409 CONFLICT when that agent already has an export in progress. A failure to create the export record or dispatch the background task returns 500 INTERNAL_ERROR. The system marks a created export as failed when dispatch fails, so that row does not block the next request. Retry a 500 with backoff. Do not change the agent ID or date range only because dispatch failed.

The session list accepts a source filter with the values widget, email, slack, api, and voice. voice is not a stored session source. It selects the sessions that have a voice call, and a call reuses the session it started in. voice results are therefore a subset of widget results, and the two counts overlap. Each session in the list carries a call object for its most recent call, or null. The messages route returns a calls array with every call on the session, oldest first. That array is empty for a chat-only session.

The API returns audio URLs one message at a time. Session deletion, alone or in bulk, removes data permanently. You must decide on data retention before you delete a session.

Give reporting jobs read-only access where possible. Limit access to individual messages. Keep dashboard metric interpretation separate from claims about answer quality. Use rate-limit headers and backoff for scheduled exports or large activity reviews.