curl --request GET \
--url https://{host}/api/public/analytics/projects/{projectId}/traces \
--header 'x-api-key: <api-key>'{
"traces": [
{
"traceId": "trace-123",
"sessionId": "sess-123",
"environment": "production",
"channel": "web_chat",
"agentName": "Support Agent",
"deploymentId": "deploy-123",
"events": [
{
"eventId": "evt-123",
"eventSeq": 7,
"eventCursor": "cursor-7",
"payloadVersion": 1,
"eventType": "llm",
"eventName": "llm.call.completed",
"timestamp": "2026-08-05T14:30:00.000Z",
"ingestedAt": "2026-08-05T14:30:00.050Z",
"spanId": "span-123",
"reasonCode": null,
"operationType": "response_gen",
"agentExecutionPolicySource": "legacy_agent",
"responseContribution": "customer_visible",
"actor": {
"actorId": "agent-123",
"actorType": "agent",
"contactId": null
},
"durationMs": 842,
"hasError": false,
"isFailure": false,
"error": null,
"eventData": {
"model": "gpt-5.2",
"provider": "openai",
"inputTokens": 120,
"outputTokens": 35,
"totalTokens": 155,
"reasoningTokens": 5,
"cachedTokens": 20,
"audioInputTokens": 0,
"audioOutputTokens": 0,
"estimatedCost": {
"amount": 0.0021,
"currency": "USD"
},
"latencyMs": 842,
"streamingUsed": true,
"toolCallCount": 0,
"timeToFirstTokenMs": 180,
"cacheCreationTokens": 0,
"finishReason": "stop",
"retryAttempt": 0
}
}
]
}
],
"pageInfo": {
"hasMore": false,
"nextCursor": null
},
"meta": {
"fromDate": "2026-08-05T00:00:00.000Z",
"toDate": "2026-08-06T00:00:00.000Z",
"dataMode": "summary",
"sortOrder": "asc",
"supportedEventTypes": [
"llm",
"tool",
"decision",
"error"
],
"supportedEventNames": [
"llm.call.completed",
"llm.call.failed",
"tool.call.completed",
"tool.call.failed",
"tool.call.skipped",
"agent.decision"
],
"unsupportedEventNamesRequested": []
}
}List trace events
List the LLM call, tool call, agent decision, and failure events recorded while agents ran, grouped by trace.
curl --request GET \
--url https://{host}/api/public/analytics/projects/{projectId}/traces \
--header 'x-api-key: <api-key>'{
"traces": [
{
"traceId": "trace-123",
"sessionId": "sess-123",
"environment": "production",
"channel": "web_chat",
"agentName": "Support Agent",
"deploymentId": "deploy-123",
"events": [
{
"eventId": "evt-123",
"eventSeq": 7,
"eventCursor": "cursor-7",
"payloadVersion": 1,
"eventType": "llm",
"eventName": "llm.call.completed",
"timestamp": "2026-08-05T14:30:00.000Z",
"ingestedAt": "2026-08-05T14:30:00.050Z",
"spanId": "span-123",
"reasonCode": null,
"operationType": "response_gen",
"agentExecutionPolicySource": "legacy_agent",
"responseContribution": "customer_visible",
"actor": {
"actorId": "agent-123",
"actorType": "agent",
"contactId": null
},
"durationMs": 842,
"hasError": false,
"isFailure": false,
"error": null,
"eventData": {
"model": "gpt-5.2",
"provider": "openai",
"inputTokens": 120,
"outputTokens": 35,
"totalTokens": 155,
"reasoningTokens": 5,
"cachedTokens": 20,
"audioInputTokens": 0,
"audioOutputTokens": 0,
"estimatedCost": {
"amount": 0.0021,
"currency": "USD"
},
"latencyMs": 842,
"streamingUsed": true,
"toolCallCount": 0,
"timeToFirstTokenMs": 180,
"cacheCreationTokens": 0,
"finishReason": "stop",
"retryAttempt": 0
}
}
]
}
],
"pageInfo": {
"hasMore": false,
"nextCursor": null
},
"meta": {
"fromDate": "2026-08-05T00:00:00.000Z",
"toDate": "2026-08-06T00:00:00.000Z",
"dataMode": "summary",
"sortOrder": "asc",
"supportedEventTypes": [
"llm",
"tool",
"decision",
"error"
],
"supportedEventNames": [
"llm.call.completed",
"llm.call.failed",
"tool.call.completed",
"tool.call.failed",
"tool.call.skipped",
"agent.decision"
],
"unsupportedEventNamesRequested": []
}
}dataMode, either summary information or the complete sanitized request and response content.
Use dataMode=summary when you need operational information such as the event type, model, token usage, duration, cost, or error status without retrieving the event payloads. Use dataMode=full when you need the detailed sanitized request and response content associated with the events. To also return the response headers of HTTP tool calls, see Response headers.
Authenticate with the x-api-key header. The key must be bound to the project you are querying and have the analytics:read permission.
The endpoint requires a fromDate and toDate range. The start of the range is inclusive and the end is exclusive. You can further narrow the results by event type, event name, session, trace, event, agent, decision type, channel, environment, or error status. Results are paginated using a cursor; because pagination counts events before grouping them into traces, a page can contain fewer traces than the requested event limit.
To get the next page, pass the nextCursor value from the response as cursor, and keep every other parameter the same. A cursor is tied to the filters, data mode, and sort order that created it, and changing any of them makes it invalid. Use limit to set the number of events per page, from 1 to 10,000. The default is 100.
Filters
fromDate: Required. Inclusive start timestamp for the time range.toDate: Required. Exclusive end timestamp for the time range.eventTypes: Filter by event category:llm: LLM callstool: Tool callsdecision: Agent decisionserror: LLM and tool failures
eventNames: Filter by specific event names:llm.call.completedllm.call.failedtool.call.completedtool.call.failedtool.call.skippedagent.decision
sessionIds: Filter events belonging to specific sessions; up to 10,000 session IDs.eventId: Return only the event with the specified ID. Use this when you need to retrieve a specific event; there is no separate single-event endpoint.traceId: Return only events belonging to the specified trace.agentName: Filter events produced by a specific agent. The value is matched exactly.decisionKind: Filter agent decision events by decision type, such asrouting,handoff,escalation, orcompletion.channel: Filter by the exact channel name recorded for the event. Pass a single value. Unlike the Sessions endpoint, this filter does not support channel aliases, so useweb_chatrather thanweb.environment: Filter by environment:dev,staging,production, orworking-copy. Pass a single value.hasError: Set totrueto return only events with errors,falseto return only events without errors, or omit the parameter to return both.
eventTypes filter accepts up to four categories. The eventNames filter accepts up to 20 names. Unsupported event names are ignored rather than rejected and are reported in meta.unsupportedEventNamesRequested.
Response headers
SetincludeResponseHeaders to true to return the response headers of HTTP tool calls. The headers appear under eventData.payloadData.responseHeaders. The default is false.
- The parameter requires
dataMode=full. - Header names are lowercase. Repeated headers are joined with a comma and a space.
- Credential headers, such as
authorization,set-cookie, andx-api-key, keep their name. Their value is[REDACTED]. - When the call was retried, the headers come from the final attempt.
responseHeadersis an empty object when the event has no headers. This happens when the tool is not an HTTP tool, no response arrived, or the event was recorded before header capture existed.responseHeadersTruncatedistruewhen headers were dropped to keep the stored names and values within 16 KB.
true, false, 1, or 0. Other values and invalid combinations return a 400 error:
| Error code | Cause |
|---|---|
INVALID_PARAM_COMBINATION | includeResponseHeaders=true with dataMode=summary, or without dataMode. |
INVALID_INCLUDE_RESPONSE_HEADERS | A value other than true, false, 1, or 0. |
Workflow runs
When a tool call starts a workflow, the event includes the run ineventData.workflowRun. This applies to tool events where toolType is workflow, including tool.call.failed events. The object lists the steps in the order they ran. It doesn’t include step inputs or outputs.
| Field | Description |
|---|---|
executionId | The ID of the run. |
workflowId | The ID of the workflow. |
workflowName | The name of the workflow. |
status | The status of the run, such as running, completed, or failed. |
startedAt, completedAt | The start and end timestamps of the run. |
durationMs | The duration of the run in milliseconds. |
stepAvailability | complete, or partial when some steps aren’t available yet. The steps list then holds only the available steps. |
stepsTruncated | true when the run has more than 200 steps. Only the first 200 are listed. |
steps | The top-level steps of the run. Steps that a loop runs for each item aren’t listed. |
steps has the following fields:
| Field | Description |
|---|---|
name | The name of the step, as written in the workflow. |
stepId | The ID of the step. |
nodeType | The kind of step, such as http, function, or email. |
status | running, completed, failed, rejected, skipped, cancelled, or a waiting_ status such as waiting_approval. |
startedAt, completedAt | The start and end timestamps of the step. |
durationMs | The duration of the step in milliseconds. |
error | The code and message of a failed step. The message has personal data removed under the project’s PII settings. |
workflowRun is absent when the run could not be loaded. The events are still complete. In that case, meta.warnings explains why.
Warnings
meta.warnings is present only when part of the page could not be served in full. Each warning has a code and a message. The only code is WORKFLOW_STEPS_UNAVAILABLE. It means some workflow tool calls are returned without workflowRun. The events themselves are complete.
Use GET when:
- You are retrieving trace data without requiring encrypted request parameters.
- You want to inspect or troubleshoot a specific event using
eventId. - You want to investigate a particular trace using
traceId. - You are analyzing events for one or more sessions using
sessionIds. - You need to query and page through trace data using standard URL parameters.
Authorizations
Query Parameters
Filter by category of event. Pass one or more values, comma-separated or by
repeating the parameter. An unrecognised value is rejected with 400.
Each category covers a fixed set of event names: llm covers
llm.call.completed; tool covers tool.call.completed and
tool.call.skipped; decision covers agent.decision; and error covers
both failure events, llm.call.failed and tool.call.failed.
4llm, tool, decision, error Filter by specific event name, when eventTypes is broader than you need.
Pass up to 20 values, comma-separated or by repeating the parameter.
Unrecognised names are not rejected. They are ignored and returned to you in
meta.unsupportedEventNamesRequested, so only the names listed below will
actually select data.
20llm.call.completed, llm.call.failed, tool.call.completed, tool.call.failed, tool.call.skipped, agent.decision Filter agent decision events by the kind of decision made, for example
routing or escalation.
Matched exactly, and not restricted to a fixed list — new decision kinds can be added by the platform at any time, so an unrecognised value returns no results rather than an error. The values below are the ones currently in use.
1Filter by the channel the conversation took place on. Pass a single value; if you repeat the parameter only the first value is used, and a comma-separated list is treated as one literal value rather than a list.
Matched exactly as stored, with no alias handling. This differs from the
sessions endpoint, which accepts shorthand such as web or sms and
expands it. Here you must use the exact channel name: web_chat rather than
web, twilio_sms rather than sms, and the specific voice channel such
as voice_vxml or audiocodes rather than voice.
Not restricted to a fixed list, so an unrecognised value returns no results rather than an error, and a newly added channel works before the list below is updated.
http_async, slack, line, msteams, whatsapp, messenger, instagram, twilio_sms, zendesk, telegram, genesys, genesys_open_messaging, ai4w, kore_agent_assist, email, voice_vxml, korevg, audiocodes, genesys_audio_connector, voice_pipeline, voice_realtime, voice, voice_twilio, voice_livekit, ag_ui, a2a, sdk_websocket, web_debug, web_chat, api, http Filter by the environment the events were recorded in. Pass a single value; if you repeat the parameter only the first value is used.
Matched exactly as stored. Not restricted to a fixed list, so an unrecognised value returns no results rather than an error.
dev, staging, production, working-copy Set to true to return the response headers of HTTP tool calls under
eventData.payloadData.responseHeaders. Requires dataMode=full; with
summary (or no dataMode) the request returns 400
INVALID_PARAM_COMBINATION. Credential headers (for example authorization,
set-cookie, x-api-key) appear with the value [REDACTED]. Accepts true,
false, 1, or 0; any other value returns 400
INVALID_INCLUDE_RESPONSE_HEADERS. Omit or set false for the default
response.
Response
Trace event page returned successfully.
- Option 1
- Option 2
Was this page helpful?