Skip to main content
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. 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}.

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 and 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.