Skip to main content

List traces

POST 
/api/v1/evals/list-traces

Lists traces for the authenticated tenant, newest first — the only ordering, so an orderBy other than timestamp.desc is rejected with HTTP 400. One trace is one conversation turn.

Filtering by entity​

Section ID: DOC-IS-evaluation-api-listTraces#filtering-by-entity

conversationId, profileId, userId and sessionId are applied at the source, not over the returned page. Repeated entity filters intersect: conversationId + profileId returns turns in that conversation produced by that profile, not the union.

cursorPage.totalItems is the only total any cursor-paged operation returns, and it is omitted whenever a profile, config-hash or level filter is set — that total cannot be counted exactly — or the count is unavailable.

conversationId accepts the bare thread id — it is qualified with your verified tenant server-side, so an id held by a product surface works without the caller reconstructing the tenant-prefixed form.

The filters array is the general filter-builder vocabulary. Entity columns there (conversationId, profileId, configHash, sourceUserMessageId) accept an exact = match or any of a set. A level row matches traces with at least one observation at that level. Latency, token and cost columns are aggregates over a trace and cannot be filtered here (use list-observations). A filter row the underlying store cannot express — an inexact operator on an entity column, an aggregate column, or an unsupported column — is rejected with HTTP 400 rather than applied to the returned page.

Historical untagged traces can remain absent from entity-filtered results. The legacy tag-backfill operation has been removed; do not infer absence of a conversation from an empty tag query.

Trace query support​

Section ID: DOC-IS-evaluation-api-listTraces#trace-query-support

A profile filter cannot be combined with level, and free-text search is not implemented. Narrow the supported profile/time query instead of relying on an ignored search setting.

For aggregate analysis, use supported observation-level filters to investigate one step or analyze an explicitly collected dataset. Keep the unit clear: one observation's cost is not the entire turn's cost.

The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.

Use this in a guide: Find out why a customer’s reply was slow

Request​

Responses​

OK

Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.​

Section ID: DOC-IS-evaluation-api-listTraces#example-evals-listTraces-request

Request example

{}

Guide request for Find the reply the customer reported. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-IS-evaluation-api-listTraces#example-cookbook-insights-evaluation-reading-01-request

Request example

{
  "profileId": "nutrition_coach",
  "fromTime": "2026-08-01T00:00:00Z",
  "toTime": "2026-08-14T00:00:00Z",
  "pageSize": 25
}

Illustrative response shape; omitted default fields and actual outcomes depend on the operation.​

Section ID: DOC-IS-evaluation-api-listTraces#example-evals-listTraces-response

Response example

{
  "traces": [
    {
      "traceId": "example_123",
      "name": "example",
      "timestamp": "2026-09-16T12:00:00Z",
      "inputJson": "{}",
      "outputJson": "{}",
      "latencySeconds": 1,
      "totalCost": 1,
      "environment": "example",
      "tags": [
        "example"
      ],
      "metadataJson": "{}",
      "bookmarked": true,
      "version": "example",
      "release": "example",
      "userId": "example_123",
      "sessionId": "example_123",
      "observationCount": 1,
      "conversationId": "example_123",
      "sourceUserMessageId": "example_123",
      "profileId": "example_123",
      "configHash": "example",
      "inputTokens": "1",
      "outputTokens": "1",
      "totalTokens": "1",
      "errorCount": 1,
      "warningCount": 1,
      "defaultCount": 1,
      "debugCount": 1,
      "scores": [
        {
          "scoreId": "example_123",
          "targetType": "EVAL_TARGET_TYPE_TRACE",
          "targetId": "example_123",
          "name": "example",
          "dataType": "SCORE_DATA_TYPE_NUMERIC",
          "numericValue": 1,
          "stringValue": "example",
          "booleanValue": true,
          "source": "SCORE_SOURCE_JUDGE",
          "comment": "example",
          "textValue": "Example text",
          "authorUserId": "example_123",
          "configId": "example_123",
          "queueId": "example_123",
          "traceId": "example_123",
          "observationId": "example_123",
          "sessionId": "example_123",
          "datasetRunId": "example_123",
          "environment": "example",
          "metadataJson": "{}",
          "traceName": "example",
          "userId": "example_123",
          "sourceLabel": "example",
          "conversationId": "example_123",
          "messageId": "example_123",
          "messageSequence": "1",
          "profileId": "example_123",
          "configHash": "example"
        }
      ],
      "commentCount": 1
    }
  ],
  "contentRedacted": true,
  "cursorPage": {
    "nextCursor": "example",
    "limit": 1,
    "totalItems": 1
  }
}

Document ID: DOC-IS-evaluation-api-listTraces. Section identities and revisions.

SectionStable reference
List tracesDOC-IS-evaluation-api-listTraces#overview
RequestDOC-IS-evaluation-api-listTraces#request
ResponsesDOC-IS-evaluation-api-listTraces#responses