Skip to main content
GET
List trace events grouped by trace
Use this endpoint to retrieve the execution events recorded while agents run. The response groups events by trace and can include LLM calls, tool calls, agent decisions, and failures. Each event provides execution metadata and, depending on the selected 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. 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.

​
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 calls
    • tool — Tool calls
    • decision — Agent decisions
    • error — LLM and tool failures
  • eventNames — Filter by specific event names:
    • llm.call.completed
    • llm.call.failed
    • tool.call.completed
    • tool.call.failed
    • tool.call.skipped
    • agent.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 as routing, handoff, escalation, or completion.
  • channel — Filter by the exact channel name recorded for the event. Unlike the Sessions endpoint, this filter does not support channel aliases.
  • environment — Filter by environment: dev, staging, production, or working-copy.
  • hasError — Set to true to return only events with errors, false to return only events without errors, or omit the parameter to return both.
The 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. 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.

​
POST — List trace events with parameters in the request body

Use this endpoint when you need the same trace data and filtering capabilities as the GET endpoint, but want to send the query parameters in the request body instead of the URL. The POST endpoint accepts the same parameters and returns the same response as GET. The POST endpoint is particularly useful when request parameters must be encrypted. When request encryption is enabled for the Platform Key, send the TracesQueryBody as an encrypted JWE. When request encryption is disabled, send the same parameters as a plain JSON object. Response encryption is independent of request encryption; when enabled, responses other than 401 are returned as encrypted JWE payloads.

​
Filters and parameters

The POST endpoint supports the same filtering parameters as GET:
  • fromDate — Required. Inclusive start timestamp.
  • toDate — Required. Exclusive end timestamp.
  • eventTypes — Filter by event category: llm, tool, decision, or error.
  • eventNames — Filter by specific supported event name.
  • sessionIds — Filter by up to 10,000 session IDs.
  • eventId — Retrieve a specific event.
  • traceId — Filter events belonging to a specific trace.
  • agentName — Filter by the exact agent name.
  • decisionKind — Filter agent decision events by decision type.
  • channel — Filter by the exact recorded channel name.
  • environment — Filter by environment.
  • hasError — Filter for events that have or do not have errors.
  • dataMode — Select summary or full event details.
  • sortOrder — Sort results in ascending or descending order.
The POST body uses the GET parameter names as JSON property names. List parameters can be sent as JSON arrays or comma-separated strings. traceDimensions is not a parameter in this Traces API; do not use it with this endpoint. Use POST method when:
  • The request parameters must be encrypted.
  • You want to avoid exposing potentially sensitive filter values in the URL.
  • You need to send the query as a JSON object rather than URL query parameters.
When request encryption is enabled, the plaintext query object is encrypted as a flattened JWE using the configured Platform Key. A plaintext POST body is rejected when request encryption is enabled, while an encrypted body is rejected when request encryption is disabled. Do not add query parameters to a POST request. All query parameters must be supplied in the request body, and the body must be a JSON object.

Authorizations

​
x-api-key
string
header
required

Project-bound API key. Do not send an Authorization header.

Path Parameters

​
projectId
string
required
Minimum string length: 1

Query Parameters

​
fromDate
string<date-time>
required
​
toDate
string<date-time>
required
​
limit
integer
default:100

How many events to return. Counted before events are grouped into traces, so a page of 100 events may contain fewer than 100 traces.

Required range: 1 <= x <= 10000
​
cursor
string

Pass the nextCursor value from the previous response to get the next page. Keep all other parameters unchanged.

Minimum string length: 1
​
eventTypes
enum<string>[]

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.

Maximum array length: 4
Available options:
llm,
tool,
decision,
error
​
eventNames
enum<string>[]

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.

Maximum array length: 20
Available options:
llm.call.completed,
llm.call.failed,
tool.call.completed,
tool.call.failed,
tool.call.skipped,
agent.decision
​
sessionIds
string[]

Filter to specific sessions. Pass up to 10,000 session IDs, comma-separated or by repeating the parameter.

Maximum array length: 10000
Minimum string length: 1
​
eventId
string

Return only the event with this ID.

Minimum string length: 1
​
traceId
string

Return only events belonging to this trace.

Minimum string length: 1
​
agentName
string

Filter to events produced by this agent. Matched exactly; agent names are set by whoever built the project, so there is no fixed list.

Minimum string length: 1
​
decisionKind
string

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.

Minimum string length: 1
​
channel
enum<string>

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

Available options:
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
​
environment
enum<string>

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.

Available options:
dev,
staging,
production,
working-copy
​
hasError
boolean

Set to true to return only events that failed, or false for only those that succeeded. Omit to return both. Accepts true, false, 1, or 0.

​
dataMode
enum<string>
default:summary

How much detail to return per event. summary returns the key facts. full adds the complete request and response content under eventData.payloadData.

Available options:
summary,
full
​
sortOrder
enum<string>
default:asc
Available options:
asc,
desc

Response

Trace event page returned successfully.

​
traces
object[]
required

The traces on this page. One trace groups the events from a single run.

​
pageInfo
object
required

Paging information for this response.

​
meta
object
required

Echo of the query that produced this response, plus the values this API supports.