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

# Querying Runs

> Read-only helpers for fetching run metadata, metrics, files, and logs from Python.

The `pluto.query` submodule exposes read-only helpers for fetching run data without writing your own HTTP client. Use these when you want to pull metrics into a notebook, compare runs in a script, or download artifacts from a finished training job. For the underlying HTTP API, see the [API Reference](/pluto/api-reference/introduction).

Every helper that takes a run ID accepts either a numeric ID (e.g. `12345`) or a display ID (e.g. `"MMP-42"`).

```python theme={null}
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, ...)`    | Filtered list of runs in a project.                             |
| `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)`    | Time series for the requested metric names.                     |
| `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.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. Authentication is resolved from `PLUTO_API_KEY` or your saved login.