> ## 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 programmatically. Each trace carries its full list of spans plus lightweight roll-up metadata.

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

List LLM traces for a project. Each returned trace carries its full (flat) list of spans plus lightweight roll-up metadata. Traces are returned newest-first.

## Key Capabilities

* List traces for a project within a time window
* Filter traces by span attributes (a trace matches when **any** of its spans matches)
* Cursor-based pagination

## List Traces

List traces for a project within an optional time window. Traces are returned in descending start-time order (most recent first). If `start_time` and `end_time` are not provided, the last seven days are queried.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
from datetime import datetime

resp = client.traces.list(
    project="your-project-name-or-id",
    space="your-space-name-or-id",     # required when project is a name
    start_time=datetime(2024, 1, 1),   # optional
    end_time=datetime(2024, 2, 1),     # optional
    limit=100,
)

for trace in resp.traces:
    print(trace.trace_id, trace.root_span_id, len(trace.spans))
```

For details on pagination, field introspection, and data conversion (to dict/JSON/DataFrame), see [Response Objects](/docs/api-clients/python/version-8/overview#response-objects).

### Filter Traces

Use the `filter` parameter to narrow results. The expression syntax matches `client.spans.list`, but the semantics differ: a trace is returned when **any** of its spans matches the filter (the matching span is usually a child, not the root), rather than only traces whose root span matches.

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
# Traces containing at least one errored span
resp = client.traces.list(
    project="your-project-name-or-id",
    filter="status_code = 'ERROR'",
)

# Traces containing at least one LLM span
resp = client.traces.list(
    project="your-project-name-or-id",
    filter="span_kind = 'LLM'",
)

# Combine filters with AND / OR
resp = client.traces.list(
    project="your-project-name-or-id",
    filter="status_code = 'ERROR' AND span_kind = 'LLM'",
)
```