# Reading a Run

Everything a run produced is in its folder (see
[The run folder](../concepts/data_flow.md#the-run-folder)), and `Run` reads it back,
from any program, while the run is going on or years later. `Run` only reads: it
cannot change the run or disturb the measurement.

## Finding a run

A run's id, which is also the name of its folder, is the experiment's name and the
time it started: `powerscan_20260925-101534`.

```python
from plesty.lib.experiment import Run, latest_run, list_runs

list_runs("runs")                       # every run folder in runs/, oldest first
list_runs("runs", name="powerscan")     # only this experiment's runs
latest_run("runs", name="powerscan")    # the newest one

run = Run("runs/powerscan_20260925-101534")
```

The helpers in `plesty.lib.experiment.runs` work with ids directly: `run_id(name)`
makes one for the current time, `parse_run_id(text)` splits one into the experiment's
name and start time, and `check_run_id(text)` refuses a name that cannot be a folder
name, which is what `--run-id` uses.

## What a run tells you

| Call | Gives |
|---|---|
| `run.id`, `run.name`, `run.started` | the run's id, the experiment's name, and when it started |
| `run.plan` | the saved `Plan` |
| `run.config` | the settings the plan was built from |
| `run.status()` | `state` (`"not_started"`, `"running"`, `"paused"`, `"completed"`, `"canceled"` or `"aborted"`), and the counts of `completed` and `failed` steps |
| `run.progress()` | the same, plus the plan's `total` steps, the `fraction` done, the time since the start (`elapsed_s`), the mean time per step (`step_s`), an estimate of the time left (`eta_s`, `None` until a step has finished), and what the current step last reported (`step`) |
| `run.records()` | the records, one dictionary per finished step, in order |
| `run.provenance` | which versions of which packages produced the run |
| `run.local(path)` | a recorded path on the shared disk, as a path on this computer (see [Data on a Shared Disk](shared_disk.md)) |
| `run.path` | the run's folder |

```python
run = Run(latest_run("runs", name="powerscan"))
print(run.status()["state"])            # "completed"
print(run.progress()["fraction"])       # 1.0
for record in run.records():
    print(record["wavelength_nm"], record["power_w"])
```

`status()` and `progress()` read the journal again at each call, so they are current
while the run goes on.

## Watching a run as it goes

To follow a run's data as it arrives, use a viewer made with `Viz` (see
[The Viewer: Viz](../viewing/viz.md)); it reads the same folder and redraws as
records arrive.