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

# TraceQueryClient

> Query traces from the backend — list, get, summarize, and inspect spans and messages.

## Overview

`TraceQueryClient` provides read-only access to traces uploaded to the Valiqor backend. Use it to list traces, retrieve summaries, inspect messages and spans, and fetch evaluation steps from traced executions.

```python theme={"system"}
from valiqor import ValiqorClient

client = ValiqorClient(api_key="your-api-key")
tq = client.traces
```

Or standalone:

```python theme={"system"}
from valiqor.trace import TraceQueryClient

tq = TraceQueryClient(api_key="your-api-key")
```

<Tip>
  Supports context manager protocol: `with TraceQueryClient(...) as tq:`
</Tip>

***

## Constructor

```python theme={"system"}
TraceQueryClient(
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    timeout: int = 300,
)
```

| Parameter  | Type            | Default | Description                 |
| ---------- | --------------- | ------- | --------------------------- |
| `api_key`  | `Optional[str]` | `None`  | Valiqor API key.            |
| `base_url` | `Optional[str]` | `None`  | Backend URL override.       |
| `timeout`  | `int`           | `300`   | Request timeout in seconds. |

***

## Methods

### `list_traces()`

List traces with pagination and optional project filtering. If neither `project_name` nor `project_id` is provided, the project name is auto-resolved from the SDK configuration.

```python theme={"system"}
def list_traces(
    self,
    project_name: Optional[str] = None,
    project_id: Optional[str] = None,
    page: int = 1,
    page_size: int = 20,
) -> TraceListResponse
```

**Returns:** [`TraceListResponse`](/sdk/models/traces#tracelistresponse)

```python theme={"system"}
# Auto-resolve project from config
traces = client.traces.list_traces()

# Or specify explicitly
traces = client.traces.list_traces(project_name="my-app", page_size=10)
for t in traces:
    print(f"{t.trace_id} | {t.status} | {t.duration_ms}ms | {t.llm_calls} LLM calls")
```

***

### `get_trace()`

Get a trace overview by ID.

```python theme={"system"}
def get_trace(self, trace_id: str) -> TraceOverview
```

**Returns:** [`TraceOverview`](/sdk/models/traces#traceoverview)

***

### `get_summary()`

Get a detailed trace summary including token counts, costs, and diagnostics.

```python theme={"system"}
def get_summary(self, trace_id: str) -> TraceSummary
```

**Returns:** [`TraceSummary`](/sdk/models/traces#tracesummary)

```python theme={"system"}
summary = client.traces.get_summary("trace-id-123")
print(f"Duration: {summary.duration_ms}ms")
print(f"Total tokens: {summary.total_tokens}")
print(f"Cost: ${summary.total_cost:.4f}")
print(f"LLM calls: {summary.llm_calls}, Tool calls: {summary.tool_calls}")
```

***

### `get_messages()`

Get the message sequence (user/assistant/tool messages) from a trace.

```python theme={"system"}
def get_messages(self, trace_id: str) -> List[TraceMessage]
```

**Returns:** `List[`[`TraceMessage`](/sdk/models/traces#tracemessage)`]`

```python theme={"system"}
messages = client.traces.get_messages("trace-id-123")
for msg in messages:
    print(f"[{msg.role}] {msg.content[:100]}")
```

***

### `get_spans()`

Get all spans from a trace, showing the execution tree.

```python theme={"system"}
def get_spans(self, trace_id: str) -> List[TraceSpan]
```

**Returns:** `List[`[`TraceSpan`](/sdk/models/traces#tracespan)`]`

```python theme={"system"}
spans = client.traces.get_spans("trace-id-123")
for span in spans:
    indent = "  " if span.parent_span_id else ""
    print(f"{indent}{span.name} ({span.kind}) - {span.duration_ms}ms")
```

***

### `get_full_trace()`

Get the complete trace data — metadata, summary, messages, spans, retrievals, and execution tree.

```python theme={"system"}
def get_full_trace(self, trace_id: str) -> TraceFullResult
```

**Returns:** [`TraceFullResult`](/sdk/models/traces#tracefullresult)

```python theme={"system"}
full = client.traces.get_full_trace("trace-id-123")
print(f"Messages: {len(full.messages)}")
print(f"Retrievals: {len(full.retrievals)}")
```

***

### `get_eval_steps()`

Get evaluation steps that were computed during or after tracing.

```python theme={"system"}
def get_eval_steps(self, trace_id: str) -> List[TraceEvalStep]
```

**Returns:** `List[`[`TraceEvalStep`](/sdk/models/traces#traceevalstep)`]`

```python theme={"system"}
steps = client.traces.get_eval_steps("trace-id-123")
for step in steps:
    print(f"{step.metric}: {step.score} — {step.explanation}")
```

***

## Related

* [Tracer](/sdk/tracer) — Instrument and capture traces
* [Tracing Workflow](/workflows/tracing) — End-to-end tracing guide
* [Traces & Spans](/concepts/traces-and-spans) — Conceptual overview
* [Models Reference](/sdk/models) — All trace data models