List trace events 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,
          "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 grouped by trace

fromDate and toDate are required. fromDate is included in the results and toDate is not, so a full day is fromDate=2026-08-05T00:00:00Z&toDate=2026-08-06T00:00:00Z.

To page through results, pass the nextCursor value from the previous response back as cursor. Keep every other parameter the same — a cursor is tied to the filters, data mode, and sort order it was created with, and changing any of them makes it invalid.

To fetch one specific event, filter by eventId. There is no separate single-event endpoint.

If you request an event name this API does not support, it is ignored rather than rejected, and listed back to you in meta.unsupportedEventNamesRequested.

GET

api

public

analytics

projects

{projectId}

traces

List trace events 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,
          "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": []
  }
}

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.

Show child attributes

pageInfo

object

required

Paging information for this response.

Show child attributes

SDK

APIs

List trace events grouped by trace

Authorizations

Path Parameters

Query Parameters

Response