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
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
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.
Request
Responses
- 200
OK
Document ID: DOC-IS-evaluation-api-listTraces. Section identities and revisions.
| Section | Stable reference |
|---|---|
| Overview | DOC-IS-evaluation-api-listTraces#overview |
| Request | DOC-IS-evaluation-api-listTraces#request |
| Responses | DOC-IS-evaluation-api-listTraces#responses |
| Filtering by entity | DOC-IS-evaluation-api-listTraces#filtering-by-entity |
| Trace query support | DOC-IS-evaluation-api-listTraces#trace-query-support |