Quickstart

This walks the shortest useful path: connect, find runs, pull a curve, plot it.

pip install 'metrana[query]'
export METRANA_API_KEY="..."

1. Connect

from metrana.query import QueryClient

client = QueryClient(workspace_name="my-team", project_name="my-project")

2. Find the runs you care about

fetch_runs returns one row per run. Ask for the attribute and summary columns you want alongside it:

from metrana.query import AttrFilter, SeriesOrderBy, SeriesSummary

runs = client.fetch_runs(
    filter=AttrFilter("sys/status") == "CLOSED",
    order_by=SeriesOrderBy("accuracy", "max").desc(),
    attributes=["config/lr", "config/seed"],
    series_summaries=[SeriesSummary("accuracy", "max")],
    max_runs=10,
)
print(runs)

           name experiment  config/lr  config/seed  accuracy():max
0  sweep-lr-003   lr-sweep     0.0030            0          0.9412
1  sweep-lr-001   lr-sweep     0.0010            0          0.9330

3. Pull the curves

Pass those run names straight to a series fetch. The result is wide: index (run, step), one column per series.

loss = client.fetch_float_series(runs["name"].tolist(), "loss")
print(loss.head())

                        loss
run          step
sweep-lr-003 0        2.4012
             1        2.1188
             2        1.9043

Which is directly plottable — unstack the run level and pandas draws one line per run:

loss["loss"].unstack("run").plot()

4. For a chart, ask for buckets

A long run has more points than a chart has pixels. fetch_float_series_buckets compresses to a fixed number of buckets server-side, and gives you min/max/count per bucket so you can draw a band rather than a lying line:

frame = client.fetch_float_series_buckets(runs["name"].tolist(), "loss", buckets_count=500)
frame["loss"]["value"]     # the representative value
frame["loss"]["min"]       # the bucket's extremes

Next steps

Runs & projects — the tables in full.
Float series — step ranges, labels, the 1000-run limit.
Filters & ordering — the whole filter grammar.
RL environments — if your runs are reinforcement learning.