Querying Runs

The pluto.query submodule exposes read helpers for fetching run data without writing your own HTTP client, plus one write helper — upload_file — for attaching a file to a run after the fact. Use these when you want to pull metrics into a notebook, compare runs in a script, download artifacts from a finished training job, or attach an artifact to a run from outside the training process. For the underlying HTTP API, see the API Reference. Every helper that takes a run ID accepts either a numeric ID (e.g. 12345) or a display ID (e.g. "MMP-42").

import pluto

run = pluto.query.get_run("my-project", "MMP-42")                     # display ID
metrics = pluto.query.get_metrics("my-project", 12345, ["train/loss"]) # numeric ID
files = pluto.query.get_files("my-project", "MMP-42")

Helpers

Helper	Returns
`pluto.query.list_projects()`	All projects you have access to.
`pluto.query.list_runs(project, search=None, tags=None, sort=None, filters=None, ...)`	Filtered list of runs — see Filtering runs.
`pluto.query.get_run(project, run_id)`	Run metadata: name, project, status, tags, config, timestamps.
`pluto.query.get_metric_names(project, run_id)`	The set of metric names logged on the run.
`pluto.query.get_metrics(project, run_id, metric_names=None, step_min=None, step_max=None)`	Time series for the requested metric names. `step_min` / `step_max` fetch just a window of steps (inclusive) — e.g. around a spike.
`pluto.query.get_statistics(project, run_id, metric_names=None)`	Per-metric summaries: min, max, mean, last value, last step.
`pluto.query.get_files(project, run_id, file_name=None)`	Files logged on the run, optionally filtered by name.
`pluto.query.download_file(project, run_id, file_name)`	Stream a single file to local disk.
`pluto.query.upload_file(project, run_id, log_name, path, *, step=None, caption=None)`	Attach a local file to an existing run. See Uploading a file to an existing run.
`pluto.query.get_logs(project, run_id, log_type=None)`	Console logs (stdout/stderr) with optional cursor-based paging.
`pluto.query.compare_runs(project, run_ids, metric_name)`	A single metric across many runs side-by-side.
`pluto.query.leaderboard(project, metric_name, ...)`	Rank runs in a project by a single metric.

All helpers raise on the network or auth error path; otherwise they return parsed Python objects (upload_file returns None on success). Authentication is resolved from PLUTO_API_KEY or your saved login. Self-hosted deployments also need PLUTO_URL_INGEST set for upload_file, since it uploads through the ingest service rather than the main API — a bare host argument maps to http://{host}:3003.

Uploading a file to an existing run

pluto.query.upload_file attaches one file artifact to an existing run over plain HTTP — a presigned upload through the ingest service. It never creates a run handle and never touches the run’s lifecycle or metadata: no status changes, no systemMetadata writes, no sys/* metrics from the machine that calls it. That’s the key difference from pluto.init(resume=True), which reopens the run for writing and, as a side effect, overwrites its systemMetadata with the resuming machine’s environment, injects that machine’s sys/* metrics, and marks a live run terminal at interpreter exit. upload_file has none of those side effects, which makes it safe to call from a laptop, a CI job, or any machine other than the one that ran the training — against a run that’s still live.

import pluto

# Attach an eval artifact to a finished run from a separate script.
pluto.query.upload_file(
    "my-project",
    "MMP-42",
    log_name="eval/report.json",
    path="report.json",
    step=1000,
    caption="Held-out eval after training",
)

The same call is also the recovery path when the training client itself reports a file as unsent — see Upload reliability and recovery:

import pluto

pluto.query.upload_file("my-project", "MMP-42", "config/run.yaml", "run.yaml")

On failure — a rejected upload, or a local path that doesn’t exist — upload_file raises pluto.query.QueryError with the server’s reason.

Filtering runs

The API for filters is currently in preview. The API may change at any moment. Check in frequently for updates. Have feedback? Let’s get in touch at founders@trainy.ai

list_runs accepts a filters argument with a query language. It composes boolean logic ($and / $or / $not) over conditions over run configurations/status/staleness. Consider the following example that checks for runs that haven’t COMPLETED and haven’t reported any metrics in the past hour.

import pluto
from datetime import datetime, timedelta, timezone

# An ISO-8601 timestamp one hour ago — the "stale" boundary.
cutoff = (datetime.now(timezone.utc) - timedelta(hours=1)).strftime("%Y-%m-%dT%H:%M:%SZ")

# Find interrupted jobs to retry: not finished, and no data in the last hour.
stale = pluto.query.list_runs("my-project", filters={"$and": [
    {"status": {"$ne": "COMPLETED"}},
    {"heartbeat_at": {"$lt": cutoff}},
]})

Operators

Operator	Meaning
`$and`, `$or`, `$not`	Combine conditions. Multiple keys in one object are implicitly ANDed.
(bare value), `$eq`	Equals — `{"status": "RUNNING"}` is shorthand for `{"status": {"$eq": "RUNNING"}}`.
`$ne`	Not equal.
`$gt`, `$gte`, `$lt`, `$lte`	Numeric / timestamp comparison. Put two on one field for a range.
`$in`, `$nin`	Value is in / not in a list.
`$regex`	Regular-expression match (text fields).

Fields

Field	Notes
`state` / `status`	Lifecycle: `RUNNING`, `COMPLETED`, `FAILED`, `TERMINATED`, `CANCELLED`
`heartbeat_at`	Last time the run reported data (ISO-8601). `$gte` = active since; `$lt` = stale before. A run that never logged data has no heartbeat and won’t match.
`created_at`, `updated_at`	Run timestamps (ISO-8601).
`name`	Run name (supports `$regex`).
`tags`	Run tags (`$in` = has any of these).
`config.<key>`	Any value from the run’s config, e.g. `config.lr`, `config.model`.
`systemMetadata.<key>`	Any value from the run’s captured environment, e.g. `systemMetadata.gpu_model`, `systemMetadata.cuda_version`, `systemMetadata.git_branch`.
`summaryMetrics.<key>`	A metric’s last value, e.g. `summaryMetrics.val_acc`.

More examples

import pluto
from datetime import datetime, timedelta, timezone

# An ISO-8601 timestamp one hour ago — the "stale" boundary.
cutoff = (datetime.now(timezone.utc) - timedelta(hours=1)).strftime("%Y-%m-%dT%H:%M:%SZ")

# Hyperparameter slice
pluto.query.list_runs("my-project", filters={"config.lr": {"$gt": 0.001}, "config.model": "gpt"})

# Top performers by a summary metric (latest reported)
pluto.query.list_runs("my-project", filters={"summaryMetrics.val_acc": {"$gte": 0.9}})

# Slice by the captured environment — e.g. only the H100 runs off a given branch
pluto.query.list_runs("my-project", filters={
    "systemMetadata.gpu_model": "H100",
    "systemMetadata.git_branch": "main",
})

# running OR reported data in the last hour
pluto.query.list_runs("my-project", filters={"$or": [
    {"state": "running"},
    {"heartbeat_at": {"$gte": cutoff}},
]})

# stale, but active within the last day — a heartbeat range on one field
day_ago = (datetime.now(timezone.utc) - timedelta(days=1)).strftime("%Y-%m-%dT%H:%M:%SZ")
pluto.query.list_runs("my-project", filters={"$and": [
    {"status": {"$ne": "COMPLETED"}},
    {"heartbeat_at": {"$gte": day_ago, "$lt": cutoff}},
]})

filters AND-combines with search, tags, and sort on the same call, and pages with limit / offset.

Filtering on heartbeat_at or summaryMetrics.*, and any $or / $not, require a project (they’re scoped to a single project). Unknown fields or operators return a 400.

Get Started

Core

API Reference

Integrations

Migrate

Changelog

Helpers

Uploading a file to an existing run

Filtering runs

Operators

Fields

More examples

​Helpers

​Uploading a file to an existing run

​Filtering runs

​Operators

​Fields

​More examples

Helpers

Uploading a file to an existing run

Filtering runs

Operators

Fields

More examples