Traces

The traces client methods 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 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.

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.

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.

# 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'",
)

API reference

API clients

Skills

Key Capabilities

List Traces

Filter Traces

​Key Capabilities

​List Traces

​Filter Traces

Key Capabilities

List Traces

Filter Traces