> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces

> List LLM traces for a project, each carrying its full set of spans, using the Arize TypeScript SDK.

<Note>
  The `traces` functions are currently in **BETA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

## 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).

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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. |