Traces

The traces functions are currently in BETA. The API may change without notice. A one-time warning is emitted on first use.

List Traces

List traces for a given project. Each trace carries its full (flat) list of spans plus lightweight roll-up metadata. The optional filter uses the same SQL-style expression syntax as listSpans, but the semantics are trace-contains-match: a trace is returned when any of its spans matches the filter (the matching span is usually a child, not the root).

import { listTraces } from "@arizeai/ax-client";

// By project ID
const { data: traces, pagination } = await listTraces({
  project: "your_project_id",
  limit: 50,
});

// By project name (requires space)
const { data: traces, pagination } = await listTraces({
  project: "My Project",
  space: "my-space",
  startTime: new Date("2026-03-01T00:00:00Z"),
  endTime: new Date("2026-03-08T00:00:00Z"),
  filter: "status_code = 'ERROR'",
  limit: 100,
});

Parameters

Parameter	Type	Description
`project`	`string`	The project name or ID.
`space`	`string`	The space name or ID. Required when `project` is a name.
`startTime`	`Date`	Filter traces whose spans start at or after this time. Defaults to 1 week ago.
`endTime`	`Date`	Filter traces whose spans start before this time. Defaults to the current time.
`filter`	`string`	SQL-style filter expression (e.g. `"status_code = 'ERROR'"`). A trace matches when any of its spans matches.
`limit`	`number`	Maximum number of traces to return.
`cursor`	`string`	Cursor for pagination.

Trace Fields

Each returned Trace object includes:

Field	Type	Description
`traceId`	`string`	The trace ID.
`rootSpanId`	`string \| null`	The ID of the root span, if any.
`startTime`	`Date \| undefined`	When the earliest span in the trace started.
`endTime`	`Date \| undefined`	When the latest span in the trace ended.
`spansTruncated`	`boolean`	Whether the trace’s span list was truncated.
`spans`	`Span[]`	The flat list of spans belonging to the trace.

Skills

MCP server

API reference

API clients

List Traces

Parameters

Trace Fields

​List Traces

​Parameters

​Trace Fields

List Traces

Parameters

Trace Fields