Skip to main content

​
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. 
from valiqor import ValiqorClient

client = ValiqorClient(api_key="your-api-key")
tq = client.traces
Or standalone: 
from valiqor.trace import TraceQueryClient

tq = TraceQueryClient(api_key="your-api-key")
Supports context manager protocol: with TraceQueryClient(...) as tq:

​
Constructor

TraceQueryClient(
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    timeout: int = 300,
)
ParameterTypeDefaultDescription
api_keyOptional[str]NoneValiqor API key.
base_urlOptional[str]NoneBackend URL override.
timeoutint300Request 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. 
def list_traces(
    self,
    project_name: Optional[str] = None,
    project_id: Optional[str] = None,
    page: int = 1,
    page_size: int = 20,
) -> TraceListResponse
Returns: TraceListResponse 
# 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. 
def get_trace(self, trace_id: str) -> TraceOverview
Returns: TraceOverview

​
get_summary()

Get a detailed trace summary including token counts, costs, and diagnostics. 
def get_summary(self, trace_id: str) -> TraceSummary
Returns: TraceSummary 
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. 
def get_messages(self, trace_id: str) -> List[TraceMessage]
Returns: List[TraceMessage] 
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. 
def get_spans(self, trace_id: str) -> List[TraceSpan]
Returns: List[TraceSpan] 
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. 
def get_full_trace(self, trace_id: str) -> TraceFullResult
Returns: TraceFullResult 
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. 
def get_eval_steps(self, trace_id: str) -> List[TraceEvalStep]
Returns: List[TraceEvalStep] 
steps = client.traces.get_eval_steps("trace-id-123")
for step in steps:
    print(f"{step.metric}: {step.score} — {step.explanation}")