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