Query via SDK

The XeroML SDK provides typed methods for reading data from your project — traces, scores, prompts, and datasets. Use these for automation scripts, data pipelines, or feeding XeroML data into other systems.

Fetching Traces

Python

from xeroml import get_client

xeroml = get_client()

# Get a specific trace
trace = xeroml.get_trace("trace_abc123")
print(trace.input, trace.output, trace.scores)

# List traces with filters
traces = xeroml.get_traces(
    user_id="user-123",
    tags=["feature:chat"],
    from_timestamp="2025-01-01T00:00:00Z",
    limit=100,
)

for trace in traces:
    print(trace.id, trace.name, trace.total_cost)

TypeScript

import { XeroMLClient } from "@xeroml/client";

const xeroml = new XeroMLClient();

// Get a specific trace
const trace = await xeroml.getTrace("trace_abc123");
console.log(trace.input, trace.output, trace.scores);

// List traces
const traces = await xeroml.getTraces({
  userId: "user-123",
  tags: ["feature:chat"],
  fromTimestamp: "2025-01-01T00:00:00Z",
  limit: 100,
});

Fetching Scores

# Get all scores for a trace
scores = xeroml.get_scores(trace_id="trace_abc123")

# Get scores by name across all traces
accuracy_scores = xeroml.get_scores(name="accuracy", limit=1000)

Fetching Prompts

# Get the production version of a prompt
prompt = xeroml.get_prompt("my-prompt", label="production")
print(prompt.version, prompt.prompt)

# List all prompts
prompts = xeroml.get_prompts()

Fetching Datasets

# Get a dataset and its items
dataset = xeroml.get_dataset("evaluation/qa-dataset")

for item in dataset.items:
    print(item.input, item.expected_output)

Fetching Metrics

# Aggregate metrics by day
metrics = xeroml.get_metrics(
    start_date="2025-01-01",
    end_date="2025-01-31",
    group_by=["userId", "environment"],
)

for day in metrics:
    print(day.date, day.total_tokens, day.total_cost)

Observations

# Get observations for a trace
observations = xeroml.get_observations(trace_id="trace_abc123")

for obs in observations:
    print(obs.name, obs.type, obs.input, obs.output, obs.usage)

Pagination

All list methods return paginated results. Use page and limit parameters, or iterate with the SDK’s built-in iterator:

# Iterator handles pagination automatically
for trace in xeroml.iter_traces(tags=["feature:search"]):
    process(trace)