> ## Documentation Index > Fetch the complete documentation index at: https://koreai-agentplatform-dev.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List trace events using JWE payload > POST form of `GET` on this path. It accepts the same parameters as a flat JSON body (`TracesQueryBody`) instead of a query string, and returns the same response. Use it when the request parameters must be encrypted. See "Sending parameters in a POST body" and "Payload encryption" in the API description. - Request encryption off: send `TracesQueryBody` as `application/json`. - Request encryption on: send the same object encrypted as an `EncryptedRequest`, preferably as `application/jose+json`. - Response encryption on: every response except `401` is an `EncryptedResponse` with `X-ABL-Encrypted: true`. Use this endpoint when you need the same trace data and filtering capabilities as [the corresponding GET endpoint](/agent-platform/api-reference/analytics-list-traces), 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`. 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. The `POST` endpoint supports the same filtering parameters as `GET`. 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: * You must encrypt the request parameters. * 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. ## OpenAPI ````yaml agent-platform/api-specs/traces.yaml post /api/public/analytics/projects/{projectId}/traces openapi: 3.1.0 info: title: ABL Public Analytics Traces API version: 1.0.0 summary: Retrieve grouped trace events and optional full payloads. description: > Returns the execution events recorded while agents ran — LLM calls, tool calls, agent decisions, and failures — grouped by the trace they belong to. Choose how much detail you want with `dataMode`. `summary` returns the key facts about each event, such as model, token counts, duration, and whether it failed. `full` returns the same fields plus the complete request and response content for each event. Paging counts events, not traces, so a long trace can be split across two pages. Authenticate with the `x-api-key` header. The key must be bound to the project you are querying and have `analytics:read` permission. ## Sending parameters in a POST body Every GET on this API has a POST form on the same path. Send the same parameters as a flat JSON object instead of a query string. Use POST when the parameters themselves must be encrypted: a GET query string is never encrypted. GET stays available and unchanged. - Body keys are exactly the GET query parameter names. Numbers and booleans are converted to the strings the GET parser expects. List parameters accept a JSON array or a comma-separated string. - An unknown key, a `null`, or a nested value is rejected with `400 INVALID_QUERY_PARAMETER`. A body that is not a JSON object is rejected with `400 INVALID_REQUEST_BODY`. - Do not add a query string to a POST (`400 INVALID_QUERY_PARAMETER`), and do not split parameters between the query string and the body. - `Content-Type` must be `application/json` or `application/jose+json`, otherwise `415 UNSUPPORTED_MEDIA_TYPE`. - Permissions, validation, pagination and the response shape are identical to the GET form. ## Payload encryption Payload encryption is an opt-in setting on a Platform Key, configured in Studio under Settings → API Keys → Platform Keys. It has two independent toggles. Neither changes what the key may access, and both are available only to keys bound to exactly one project. **Request encryption** applies to POST bodies (a GET has no body). The body must be a JWE (RFC 7516) in flattened JSON serialization, `{protected, iv, ciphertext, tag}`, whose protected header is `{"alg":"dir","enc":"A256GCM"}`, optionally with `kid`, `typ` and `cty`. The key is the 32-byte AES-256 request key Studio shows when request encryption is enabled. `kid` is optional; if sent it must equal the key's Key ID shown in Studio. **Response encryption** applies to every response sent after the key is authenticated, successes and errors alike (400, 403, 404, 413, 415, 429, 500, 503). The body is a flattened JWE `{protected, encrypted_key, iv, ciphertext, tag}` with protected header `{"alg":"RSA-OAEP-256","enc":"A256GCM","kid":"","pkf":""}`, sealed with a fresh AES-256 key per response that is wrapped with the RSA public key (≥ 2048 bits) configured on the Platform Key. `pkf` is the SHA-256 hex digest of that public key's SubjectPublicKeyInfo DER. The response keeps `Content-Type: application/json` and adds `X-ABL-Encrypted: true`. Decrypting it yields exactly the JSON documented in this spec. A `401` is never encrypted (the key is not known yet), and a `304` has no body. | Key setting | Plain JSON body | JWE body | |---|---|---| | Request encryption off | accepted | `400 ENCRYPTED_PAYLOAD_INVALID` | | Request encryption on | `400 ENCRYPTED_PAYLOAD_INVALID` | decrypted, then handled as plain JSON | Encryption fails closed: a configured key never receives plaintext by accident. - `400 ENCRYPTED_PAYLOAD_INVALID` is returned for every envelope problem: any other `alg`/`enc`, `zip` or `crit`, unknown header parameters, `unprotected`, `header`, `aad` or `recipients` members, a `kid` that is not this key's, padded or standard base64, a wrong IV (12 bytes) or tag (16 bytes) length, a failed authentication tag, or a plaintext that is not JSON. - `503 ENCRYPTION_CONFIG_UNAVAILABLE` (with `Retry-After: 30`) means the key's encryption configuration could not be read. Retry later; there is no plaintext fallback. - `500 INTERNAL_ERROR` with a content-free body is returned if a response cannot be encrypted. All JWE members are unpadded base64url. The AAD is the ASCII of the `protected` member, as in standard JWE, so JOSE libraries (for example `jose` for Node.js) can produce and open these envelopes directly. Pin the algorithms when decrypting: key management `RSA-OAEP-256`, content encryption `A256GCM`. x-source-release: develop x-source-commit: b6a1a328b3e089e03ca2494a7091d72a6a481d4b x-payload-encryption: jira: ABLP-5317 source: develop, PR source-commit: 6de86f59eb runtime-capability: 'GET /health -> capabilities.payloadEncryption: 2' servers: - url: https://{host} variables: host: default: runtime.example.com security: - ApiKeyAuth: [] tags: - name: Traces paths: /api/public/analytics/projects/{projectId}/traces: post: tags: - Traces summary: List trace events grouped by trace (parameters in the body) description: > POST form of `GET` on this path. It accepts the same parameters as a flat JSON body (`TracesQueryBody`) instead of a query string, and returns the same response. Use it when the request parameters must be encrypted. See "Sending parameters in a POST body" and "Payload encryption" in the API description. - Request encryption off: send `TracesQueryBody` as `application/json`. - Request encryption on: send the same object encrypted as an `EncryptedRequest`, preferably as `application/jose+json`. - Response encryption on: every response except `401` is an `EncryptedResponse` with `X-ABL-Encrypted: true`. operationId: queryPublicAnalyticsTraces parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/TracesQueryBody' - $ref: '#/components/schemas/EncryptedRequest' examples: plain: summary: Request encryption off value: fromDate: '2026-08-05T00:00:00.000Z' toDate: '2026-08-06T00:00:00.000Z' eventTypes: - llm - tool dataMode: summary sortOrder: desc limit: 100 encrypted: summary: Request encryption on (JWE of the plain example) value: protected: >- eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiNjZmN2ExYzJlNGIwYTFkMmMzZTRmNWE2In0 iv: RegTSkKBi-mDYZbe ciphertext: >- 4nDRORBGYErcDJfT0KSZKFK2I-Wjch6M9EMEUDpPxwkMFCCXK5LL3gZWf08P0A3yYFc6BIQmJ_X89khBoDzZNnLEM4ZdrUF5C5nlOkoYXDJwQJNK7NK1Pa39xJc1lflC0U6UhUUt8lfcb2ACumRHO0EO0IOaVXzn0h08fPi3JQUzEz-YAcjIoU3ajYOt0nTojLEF4IaG9QhMV10vkaMRYL83EH8Y-R4 tag: LSoURcbEisQrHZiRURFQpw application/jose+json: schema: $ref: '#/components/schemas/EncryptedRequest' example: protected: >- eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiNjZmN2ExYzJlNGIwYTFkMmMzZTRmNWE2In0 iv: RegTSkKBi-mDYZbe ciphertext: >- 4nDRORBGYErcDJfT0KSZKFK2I-Wjch6M9EMEUDpPxwkMFCCXK5LL3gZWf08P0A3yYFc6BIQmJ_X89khBoDzZNnLEM4ZdrUF5C5nlOkoYXDJwQJNK7NK1Pa39xJc1lflC0U6UhUUt8lfcb2ACumRHO0EO0IOaVXzn0h08fPi3JQUzEz-YAcjIoU3ajYOt0nTojLEF4IaG9QhMV10vkaMRYL83EH8Y-R4 tag: LSoURcbEisQrHZiRURFQpw responses: '200': description: Trace event page returned successfully (same body as the GET form). headers: Cache-Control: schema: type: string example: private, no-store, max-age=0 X-ABL-Encrypted: $ref: '#/components/headers/XAblEncrypted' content: application/json: schema: oneOf: - $ref: '#/components/schemas/TraceListResponse' - $ref: '#/components/schemas/EncryptedResponse' examples: encrypted: summary: >- Response for a key with response encryption on (decrypt to get the plain body) value: protected: >- eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiNjZmN2ExYzJlNGIwYTFkMmMzZTRmNWE2IiwicGtmIjoiZDExYzNlNDcxYjRmNDU4MTA3Y2JiZmFjMzg2NWEwNDZhMjIyZjVlZDcyZDQ2MDUyNDFiMWFjYWI3MjE1MmNlNiJ9 encrypted_key: >- XScVR_HSab2Vl58k_P_5xmQaWutTpDzp7oc-1OZXrn6pLVBPx7Z2holovT7U1QWQQeWJVOKIchjQJV2eDtX1wT11kusoQMrgDsgk1kaNgxzQSgiECQUkGJnjCJCzp_wSKiYTpwshpYKYLNjo1lQBCk97ukApMmym_GUBERGQkOhc53bFVEXNd8UFZMrn7-wkChOHbwm5DbMJVboNK9Pqe4InWQRFpg6gaxIqH9XM4bkhydQUxTxwJtvY3fmKhMpT7ZeEbclUCGAHK_xUVLj9yzSadjgDoYT04DetRleOQrjBfC_qr8t3ilWZlpIeqiET5iyEFrxuhqi9zzUIs_6Njw iv: Nd51pTVdZKYz8Lt6 ciphertext: mIzOWlsoKAPVc3lQghwjHA tag: BaHsLsjLXYGESMoRsNdr4g '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '413': $ref: '#/components/responses/ResponseTooLarge' '415': $ref: '#/components/responses/UnsupportedMediaType' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/Unavailable' components: parameters: ProjectId: name: projectId in: path required: true schema: type: string minLength: 1 schemas: TracesQueryBody: type: object additionalProperties: false description: > POST form of the GET query parameters: a flat JSON object whose keys are the GET query parameter names. For a Platform Key with request encryption on, send this object encrypted as an `EncryptedRequest` instead. properties: fromDate: description: Same as the `fromDate` query parameter of the GET operation. type: string format: date-time toDate: description: Same as the `toDate` query parameter of the GET operation. type: string format: date-time limit: description: Same as the `limit` query parameter of the GET operation. type: integer minimum: 1 maximum: 10000 default: 100 cursor: description: Same as the `cursor` query parameter of the GET operation. type: string minLength: 1 eventTypes: description: >- Same as the `eventTypes` query parameter of the GET operation. Send a JSON array, or a comma-separated string as in the query string. anyOf: - type: array uniqueItems: true maxItems: 4 items: type: string enum: - llm - tool - decision - error - type: string minLength: 1 eventNames: description: >- Same as the `eventNames` query parameter of the GET operation. Send a JSON array, or a comma-separated string as in the query string. anyOf: - type: array uniqueItems: true maxItems: 20 items: type: string enum: - llm.call.completed - llm.call.failed - tool.call.completed - tool.call.failed - tool.call.skipped - agent.decision - type: string minLength: 1 sessionIds: description: >- Same as the `sessionIds` query parameter of the GET operation. Send a JSON array, or a comma-separated string as in the query string. anyOf: - type: array maxItems: 10000 uniqueItems: true items: type: string minLength: 1 - type: string minLength: 1 eventId: description: Same as the `eventId` query parameter of the GET operation. type: string minLength: 1 traceId: description: Same as the `traceId` query parameter of the GET operation. type: string minLength: 1 agentName: description: Same as the `agentName` query parameter of the GET operation. type: string minLength: 1 decisionKind: description: Same as the `decisionKind` query parameter of the GET operation. type: string minLength: 1 x-common-values: - routing - handoff - escalation - completion - retry - backtrack - stop - pause - resume - reopen - waive - save_eval_suite - promote_candidate_to_eval_suite - promote_generated_project_lifecycle channel: description: Same as the `channel` query parameter of the GET operation. type: string enum: - 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: description: Same as the `environment` query parameter of the GET operation. type: string enum: - dev - staging - production - working-copy hasError: description: Same as the `hasError` query parameter of the GET operation. type: boolean dataMode: description: Same as the `dataMode` query parameter of the GET operation. type: string enum: - summary - full default: summary sortOrder: description: Same as the `sortOrder` query parameter of the GET operation. type: string enum: - asc - desc default: asc required: - fromDate - toDate EncryptedRequest: type: object additionalProperties: false required: - protected - iv - ciphertext - tag description: > Request body for a Platform Key with request encryption on: a JWE in flattened JSON serialization (RFC 7516 §7.2.2). The plaintext is the JSON body documented for the plain POST form. Send with `Content-Type: application/jose+json` or `application/json`. properties: protected: type: string pattern: ^[A-Za-z0-9_-]+$ description: > base64url of the protected header JSON. Decodes to `RequestProtectedHeader`. Its ASCII is also the AES-GCM additional authenticated data. encrypted_key: type: string maxLength: 0 description: 'Empty or omitted: `dir` has no wrapped key.' iv: type: string pattern: ^[A-Za-z0-9_-]+$ description: base64url of a fresh random 12-byte AES-GCM IV. ciphertext: type: string pattern: ^[A-Za-z0-9_-]+$ description: base64url of the AES-256-GCM ciphertext. tag: type: string pattern: ^[A-Za-z0-9_-]+$ description: base64url of the 16-byte AES-GCM authentication tag. TraceListResponse: type: object additionalProperties: false required: - traces - pageInfo - meta properties: traces: type: array items: $ref: '#/components/schemas/Trace' description: > The traces on this page. One trace groups the events from a single run. pageInfo: $ref: '#/components/schemas/PageInfo' description: | Paging information for this response. meta: $ref: '#/components/schemas/TraceMeta' description: > Echo of the query that produced this response, plus the values this API supports. EncryptedResponse: type: object additionalProperties: false required: - protected - encrypted_key - iv - ciphertext - tag description: > Response body for a Platform Key with response encryption on (signalled by the `X-ABL-Encrypted: true` header): a JWE in flattened JSON serialization. The decrypted plaintext is the JSON body documented for that status code. properties: protected: type: string pattern: ^[A-Za-z0-9_-]+$ description: >- base64url of the protected header. Decodes to `ResponseProtectedHeader`. encrypted_key: type: string pattern: ^[A-Za-z0-9_-]+$ description: >- The per-response AES-256 key, wrapped with the customer's RSA public key using RSA-OAEP-256. iv: type: string pattern: ^[A-Za-z0-9_-]+$ description: base64url of the 12-byte AES-GCM IV (fresh per response). ciphertext: type: string pattern: ^[A-Za-z0-9_-]+$ description: base64url of the AES-256-GCM ciphertext. tag: type: string pattern: ^[A-Za-z0-9_-]+$ description: base64url of the 16-byte AES-GCM authentication tag. Trace: type: object additionalProperties: false required: - traceId - sessionId - environment - channel - agentName - deploymentId - events properties: traceId: type: - string - 'null' description: > Identifier shared by all events from one run. Null when the events were recorded without one. sessionId: type: string description: | The conversation these events belong to. environment: type: - string - 'null' description: Empty values are normalized to `null` on output. enum: - dev - staging - production - working-copy - null channel: type: - string - 'null' description: > The channel the conversation took place on, exactly as recorded. `null` when the event was not tied to a channel. enum: - 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 - null agentName: type: - string - 'null' description: | The agent that ran. Null when not recorded. deploymentId: type: - string - 'null' description: | The deployment the agent was running under. events: type: array items: $ref: '#/components/schemas/TraceEvent' description: > The events in this trace that fall on the current page. A long trace can continue on the next page. PageInfo: type: object additionalProperties: false required: - hasMore - nextCursor properties: hasMore: type: boolean description: | Whether more pages are available after this one. nextCursor: type: - string - 'null' description: > Pass this back as `cursor` to fetch the next page. Null on the last page. TraceMeta: type: object additionalProperties: false required: - fromDate - toDate - dataMode - sortOrder - supportedEventTypes - supportedEventNames - unsupportedEventNamesRequested properties: fromDate: type: string format: date-time description: | The start of the range applied to this response. toDate: type: string format: date-time description: | The end of the range applied to this response. dataMode: type: string enum: - summary - full description: | The detail level applied to this response. sortOrder: type: string enum: - asc - desc description: | The sort order applied to this response. supportedEventTypes: type: array items: type: string enum: - llm - tool - decision - error description: | Every event category this API can return. supportedEventNames: type: array description: The complete set of event names this API can select. items: type: string enum: - llm.call.completed - llm.call.failed - tool.call.completed - tool.call.failed - tool.call.skipped - agent.decision unsupportedEventNamesRequested: type: array description: > Any `eventNames` values you sent that this API does not support. They were ignored rather than rejected. Use this to spot typos when a query returns fewer results than expected. items: type: string ErrorEnvelope: type: object required: - error properties: success: type: boolean const: false description: | Always false on an error response. error: description: > Details of what went wrong. `code` is a stable machine-readable value; `message` is human-readable. type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true message: type: string description: >- Present on some authorization denials in addition to `error.message`. required: description: >- Permission(s) the caller was missing. Present on authorization denials. oneOf: - type: string - type: array items: type: string TraceEvent: oneOf: - $ref: '#/components/schemas/LlmEvent' - $ref: '#/components/schemas/ToolEvent' - $ref: '#/components/schemas/DecisionEvent' - $ref: '#/components/schemas/ErrorEvent' discriminator: propertyName: eventType mapping: llm: '#/components/schemas/LlmEvent' tool: '#/components/schemas/ToolEvent' decision: '#/components/schemas/DecisionEvent' error: '#/components/schemas/ErrorEvent' LlmEvent: allOf: - $ref: '#/components/schemas/EventBase' - type: object properties: eventType: const: llm eventName: const: llm.call.completed eventData: $ref: '#/components/schemas/LlmEventData' description: | The event details, which differ by event type. ToolEvent: allOf: - $ref: '#/components/schemas/EventBase' - type: object properties: eventType: const: tool eventName: type: string enum: - tool.call.completed - tool.call.skipped eventData: $ref: '#/components/schemas/ToolEventData' DecisionEvent: allOf: - $ref: '#/components/schemas/EventBase' - type: object properties: eventType: const: decision eventName: const: agent.decision eventData: $ref: '#/components/schemas/DecisionEventData' ErrorEvent: allOf: - $ref: '#/components/schemas/EventBase' - type: object properties: eventType: const: error eventName: type: string enum: - llm.call.failed - tool.call.failed eventData: type: object additionalProperties: false properties: payloadData: $ref: '#/components/schemas/PayloadData' EventBase: type: object required: - eventId - eventSeq - eventCursor - payloadVersion - eventType - eventName - timestamp - ingestedAt - spanId - reasonCode - operationType - agentExecutionPolicySource - responseContribution - actor - durationMs - hasError - isFailure - error - eventData properties: eventId: type: string description: > Identifier of this event. Pass it to the `eventId` filter to fetch just this one. eventSeq: type: - integer - 'null' minimum: 0 description: | Position of this event in the run, used to keep events in order. eventCursor: type: - string - 'null' description: > Paging marker for this event. Not usually needed — use `pageInfo.nextCursor` instead. payloadVersion: type: - integer - 'null' minimum: 0 description: > Internal version of the event format. Useful only when comparing old and new records. eventType: type: string enum: - llm - tool - decision - error description: | Category of event. eventName: type: string enum: - llm.call.completed - llm.call.failed - tool.call.completed - tool.call.failed - tool.call.skipped - agent.decision description: | The specific event that was recorded. timestamp: type: string format: date-time description: | When the event happened. ingestedAt: type: - string - 'null' format: date-time description: | When the platform stored the event. Slightly later than `timestamp`. spanId: type: - string - 'null' description: > Identifier for this step within the trace, for lining events up with external tracing tools. reasonCode: type: - string - 'null' description: > A short code explaining why the event happened or what it resulted in, for example the reason a decision was taken or a call failed. Not restricted to a fixed list — each part of the platform sets its own codes, and for some event kinds this falls back to the event name itself. `null` when the event records no reason. operationType: type: - string - 'null' description: > What the LLM call was being used for. For agent responses this is normally `response_gen` (generating a reply) or `coordination` (deciding where to route). Other parts of the platform — guardrails, pipelines, Arch, SearchAI, and Studio test calls — set their own values, so this is not restricted to a fixed list. The values below are the most common. x-common-values: - response_gen - coordination - extraction - validation - tool_selection - reasoning x-other-producer-values: - chat_complete - guardrail_evaluation - realtime_response - pipeline_classify - pipeline_generate_text - pipeline_generate_object - route_selection - response_synthesis agentExecutionPolicySource: type: - string - 'null' description: > How the platform worked out what role the agent was playing. `explicit` means the agent declares its role directly, which is the current approach. The three `legacy_` values mean the role had to be inferred from an older agent definition. Always one of these four values, or `null` when the event is not an agent LLM call. enum: - explicit - legacy_agent - legacy_supervisor_flag - legacy_compiled_route_only - null responseContribution: type: - string - 'null' description: > Whether this event's output reached the end user. `customer_visible` means it formed part of the reply; `internal_only` means it was used behind the scenes. Not restricted to a fixed list, though the values below are the ones the platform currently sets. x-common-values: - internal_only - customer_visible - customer_visible_candidate - customer_visible_interim - none - simulated actor: description: Who or what triggered the event. Null when not recorded. oneOf: - $ref: '#/components/schemas/Actor' - type: 'null' durationMs: type: - integer - 'null' minimum: 0 description: | How long the step took, in milliseconds. hasError: type: boolean description: | Whether this event was recorded with an error flag. isFailure: type: boolean description: > Whether this event counts as a failure under the platform failure rule. This is the rule behind a session's `errorCount`: handled errors, superseded LLM retry attempts and warnings are not failures. For the event names this endpoint returns, `isFailure` equals `hasError`. error: description: > Details of what went wrong. `code` is a stable machine-readable value; `message` is human-readable. oneOf: - $ref: '#/components/schemas/EventError' - type: 'null' LlmEventData: type: object additionalProperties: false required: - model - provider - inputTokens - outputTokens - totalTokens - reasoningTokens - cachedTokens - audioInputTokens - audioOutputTokens - estimatedCost - latencyMs - streamingUsed - toolCallCount - timeToFirstTokenMs - cacheCreationTokens - finishReason - retryAttempt properties: model: type: string description: | The model used for this call. provider: type: string description: | The provider that served the call, such as `openai` or `azure`. inputTokens: type: - integer - 'null' minimum: 0 description: | Tokens in the prompt sent to the model. outputTokens: type: - integer - 'null' minimum: 0 description: | All tokens the model produced — answer plus any reasoning. totalTokens: type: - integer - 'null' minimum: 0 description: | Input plus output tokens for this call. reasoningTokens: type: - integer - 'null' minimum: 0 description: > Tokens spent on internal model reasoning. Billed as output but not part of the visible answer. cachedTokens: type: - integer - 'null' minimum: 0 description: > Input tokens served from the provider prompt cache. Part of inputTokens, and usually cheaper. audioInputTokens: type: - integer - 'null' minimum: 0 description: | Audio tokens in the prompt, for voice models. audioOutputTokens: type: - integer - 'null' minimum: 0 description: | Audio tokens in the response, for voice models. estimatedCost: description: > Estimated cost of this call. Null when no price is known for the model. oneOf: - $ref: '#/components/schemas/Money' - type: 'null' latencyMs: type: - integer - 'null' minimum: 0 description: | How long the call took, in milliseconds. streamingUsed: type: - boolean - 'null' description: | Whether the response was streamed back token by token. toolCallCount: type: - integer - 'null' minimum: 0 description: | How many tool calls the model asked for in this response. timeToFirstTokenMs: type: - integer - 'null' minimum: 0 description: > Time until the first token arrived, in milliseconds. Meaningful for streamed calls. cacheCreationTokens: type: - integer - 'null' minimum: 0 description: > Input tokens written into the provider prompt cache for reuse by later calls. finishReason: type: - string - 'null' description: > Why the model stopped generating: `stop` when it finished normally, `length` when it hit the token limit, `tool_calls` when it asked to call a tool, `content_filter` when output was blocked, `error` on failure. Provider-specific wording is converted to these five values where the platform recognises it, but an unconverted provider value can still appear. x-common-values: - stop - length - tool_calls - content_filter - error retryAttempt: type: - integer - 'null' minimum: 0 description: | Which attempt this was. 0 on the first try, higher after a retry. payloadData: $ref: '#/components/schemas/PayloadData' ToolEventData: type: object additionalProperties: false required: - toolName - toolType - success - latencyMs - resultSizeBytes - executionSkipped - operationalFailure properties: toolName: type: string description: | Name of the tool that was called. toolType: type: - string - 'null' description: > What kind of tool was called — an HTTP endpoint, an MCP server, a workflow, and so on. The values below cover the built-in tool kinds; a custom tool can report its own value. x-common-values: - http - mcp - sandbox - lambda - connector - workflow - searchai - async_webhook - table success: type: - boolean - 'null' description: | Always false on an error response. latencyMs: type: - integer - 'null' minimum: 0 description: | How long the tool call took, in milliseconds. resultSizeBytes: type: - integer - 'null' minimum: 0 description: | Size of what the tool returned, in bytes. executionSkipped: type: - boolean - 'null' description: > True when the tool was chosen but not actually run — for example when a guard blocked it. operationalFailure: type: - boolean - 'null' description: > True when the tool failed for an infrastructure reason, such as a timeout, rather than returning a normal error. payloadData: $ref: '#/components/schemas/PayloadData' DecisionEventData: type: object additionalProperties: false required: - decisionKind - decision - outcome - matched - reasoning properties: decisionKind: type: string description: > The kind of decision the agent made, for example `routing` or `escalation`. Not restricted to a fixed list, since new decision kinds can be added at any time. Returned as `unknown` when the event does not record one. x-common-values: - routing - handoff - escalation - completion - retry - backtrack - stop - pause - resume - reopen - waive - save_eval_suite - promote_candidate_to_eval_suite - promote_generated_project_lifecycle - unknown decision: type: - string - 'null' description: > What the agent decided, such as the agent it routed to. Free text, and not always present. outcome: type: - string - 'null' description: > The agent's stated reasoning. Always `null` in `summary` mode; look in `payloadData.details` when using `dataMode=full`. matched: type: - boolean - 'null' description: | Whether the decision matched a configured rule. reasoning: type: - string - 'null' description: >- Summary mode currently returns null; detailed reasoning may be in full-mode payload details. payloadData: $ref: '#/components/schemas/PayloadData' PayloadData: type: object additionalProperties: false description: > The full content of the event, returned only when `dataMode=full`. LLM calls use `request` and `response`; tool calls and decisions use `input`, `output`, and `details`. properties: request: description: Complete sanitized LLM request payload response: description: Complete sanitized LLM response payload input: description: Complete sanitized event input output: description: Complete sanitized event output details: type: object additionalProperties: true description: Remaining sanitized event-specific fields. Actor: type: object additionalProperties: false required: - actorId - actorType - contactId properties: actorId: type: - string - 'null' description: | Identifier of the user, contact, or agent that triggered the event. actorType: type: - string - 'null' description: > Who or what triggered the event: `user` or `contact` for a person, `agent` for an AI agent, `system` for the platform itself. Anything else is returned as `null`. enum: - user - contact - system - agent - null contactId: type: - string - 'null' description: > The contact record associated with the event, when the actor is a known person. EventError: type: object additionalProperties: false required: - type - message properties: type: type: - string - 'null' description: > A short error identifier, such as a platform error code or the name of the underlying error class. Free text, limited to letters, digits, and the characters `_ . : -`. Anything longer or containing other characters is returned as `null`. pattern: ^[a-zA-Z0-9_.:-]{1,128}$ maxLength: 128 x-common-values: - internal_error - unknown_error - app_error - execution_error - llm_error - provider_error - channel_send_failed - channel_send_exception - channel_adapter_unavailable - webhook_delivery_failed - webhook_client_error - websocket_not_open - voice_setup_error - tts_delivery_failure message: type: - string - 'null' description: Currently redacted to null on the public surface. Money: type: object additionalProperties: false required: - amount - currency properties: amount: type: number minimum: 0 description: | The cost amount. currency: type: string description: > Three-letter currency code, uppercase. `USD` unless the recorded cost specifies something else. pattern: ^[A-Z]{3}$ default: USD example: USD headers: XAblEncrypted: description: >- Present with value `true` when the body is an `EncryptedResponse`. Absent otherwise. schema: type: string enum: - 'true' responses: BadRequest: description: > Invalid date range, filter, data mode, limit, sort order, boolean, or cursor. Encryption and POST-body errors also return 400: `ENCRYPTED_PAYLOAD_INVALID` (malformed, unexpected or undecryptable JWE, or a plain body for a request-encrypted key), `INVALID_REQUEST_BODY` (POST body is not a JSON object), and `INVALID_QUERY_PARAMETER` (unknown, null or nested POST body key, or a query string on a POST). content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/EncryptedResponse' Unauthorized: description: Missing or invalid `x-api-key`, or Authorization was supplied. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Forbidden: description: The key lacks `analytics:read`. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/EncryptedResponse' NotFound: description: Project not found or concealed because it is outside the key's scope. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/EncryptedResponse' ResponseTooLarge: description: One full-mode event exceeds the 1 MiB response budget. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/EncryptedResponse' UnsupportedMediaType: description: >- A POST body was sent with a `Content-Type` other than `application/json` or `application/jose+json` (`UNSUPPORTED_MEDIA_TYPE`). content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/EncryptedResponse' RateLimited: description: Tenant request rate limit exceeded. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/EncryptedResponse' InternalError: description: > Unexpected trace query failure. Also returned, with a content-free body, when a response cannot be encrypted for a response-encrypted key. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/EncryptedResponse' Unavailable: description: > Trace backing store unavailable. `ENCRYPTION_CONFIG_UNAVAILABLE` (with `Retry-After: 30`) means the Platform Key's payload-encryption configuration could not be read. There is no plaintext fallback. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/EncryptedResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: Project-bound API key. Do not send an Authorization header. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.