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.

GET /agents/{id}/activity/sessions follows the same rules for its dateFrom and dateTo filters. A date-only dateTo includes the full UTC day, a timestamp needs an explicit time zone, and epoch milliseconds, RFC 2822 dates, and timestamps without a zone return 400. A reversed range is 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.

Find the replies that went wrong

GET /mcp/agents/{agentId}/answer-gaps lists the replies of one agent that went wrong, newest first. Each item gives the visitor question, the answer, the confidence, the threshold of the agent, the conversation ID, and one or more reasons:

• low_confidence: the retrieval confidence is below the threshold of the agent. A confidence equal to the threshold is not a gap.
• no_match: the search ran and did not fail, but the reply has no confidence. A reply whose search did not run, such as a greeting or a tool-approval continuation, is not no_match. An old reply with no retrieval data is not no_match either.
• retrieval_failed: the search itself failed.
• escalated: the agent escalated to a human during this reply.
• negative_feedback: the visitor gave the reply a thumbs-down.

When you give no from and no to, the window is the last 30 days. When you give only to, the window is the 30 days that end at to. A window longer than 365 days, a reversed window, or a malformed cursor is refused with 400 INVALID_INPUT. limit is 20 by default and 100 at most. To get the next page, send nextCursor back as cursor. An agent outside your organization is refused with 404 AGENT_NOT_FOUND.

GET /mcp/messages/{messageId}/answer-trace returns the stored retrieval evidence of one reply: the confidence, the threshold, the retrieval mode, the number of passages, and the source documents with their scores. A reply stored before this evidence was recorded returns null fields, not an error. A message outside your organization is refused with 404 MESSAGE_NOT_FOUND.

Both routes are read-only and spend no credits. They are also the MCP tools list_answer_gaps and get_answer_trace.

Changes

• 2026-09-24 — New route GET /mcp/agents/{agentId}/answer-gaps lists the replies of an agent that had low confidence, found no match, failed retrieval, escalated, or got a thumbs-down.
• 2026-09-24 — New route GET /mcp/messages/{messageId}/answer-trace returns the stored retrieval evidence of one reply.