Prerequisites
- A Platform Key bound to the project you query. Send it in the
x-api-keyheader. - The
session:readpermission on the key for session summaries. The other endpoints needanalytics: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 (
fromDateandtoDate) or a list ofsessionIds. Trace events and LLM calls need a date range. - Trace events and LLM calls return key facts by default. Set
dataModetofullto include the request and response content. - Trace events can include the response headers of HTTP tool calls. Set
includeResponseHeaderstotrueanddataModetofull. 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.warningswhen part of the page can’t be served in full. For example,WORKFLOW_STEPS_UNAVAILABLEmeans some workflow tool calls come back without their run steps. The events are still complete. See Warnings. - Session summaries return only
user_initiatedsessions unless you setsource. Earlier versions returned every source. Sendsource=allto include evaluation, debug, workflow, synthetic, and demo sessions. See Source. - The session summaries
channelfilter matches the exact channel ID and doesn’t group channels into families. UsechannelTypeto filter by family, such asvoice. 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
limitso the response stays within 1 MiB. CheckhasMoreinstead of assuming a short page is the last one. For conversation messages, usecursorfor 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.