RunHandle¶

Returned by submit_training_run(), submit_training_sweep(), and submit_run(). Provides methods for monitoring and downloading results.

Properties¶

Property	Type	Description
`id`	`int`	Numeric run ID
`slug`	`str`	URL-safe identifier (`run_` + 8 chars)
`name`	`str`	Human-readable name
`status`	`str`	`queued`, `running`, `completed`, or `failed`
`dashboard_url`	`str`	Dashboard URL for this run
`tensorboard_url`	`str`	TensorBoard URL
`progress`	`float`	Completion fraction (0.0 to 1.0)

run.refresh() -> RunHandle

Refresh run state from the server. Returns self for chaining.

run.refresh()
print(f"Status: {run.status}, Progress: {run.progress:.0%}")

run.wait_for_completion(
    timeout: float | None = None,
    poll_interval: float = 5.0,
    show_progress: bool = True,
) -> RunHandle

Block until the run completes or fails.

Parameter	Default	Description
`timeout`	`None`	Max seconds to wait. `None` = wait forever
`poll_interval`	`5.0`	Seconds between status checks
`show_progress`	`True`	Show a Rich progress bar in the terminal

Raises: TimeoutError if timeout exceeded.

run.wait_for_completion(timeout=3600, show_progress=True)

run.get_metrics() -> RunMetrics

Get aggregated metrics for this run.

run.get_tasks() -> list[Task]

Get all tasks for this run.

run.download_results(
    output_dir: Path | str,
    include_tensorboard: bool = False,
) -> Path

Download all completed task results to a local directory.

Raises: ResultsNotReadyError if the run hasn't completed.

run.list_artifacts(artifact_type: str | None = None) -> list[dict]

List artifacts. Optionally filter by type.

run.list_checkpoints() -> list[dict]

List checkpoint artifacts.

run.list_videos() -> list[dict]

List video artifacts.

run.download_artifact(s3_key: str, output_dir: Path | str) -> Path

Download a specific artifact by S3 key.

run.download_checkpoint(filename: str, output_dir: Path | str) -> Path

Download a checkpoint by filename (e.g., "model_5000.pt").

Raises: RunNotFoundError if the checkpoint doesn't exist.

run.download_best_checkpoint(output_dir: Path | str) -> Path

Download the latest/best checkpoint (last by filename sort order).

Raises: ResultsNotReadyError if no checkpoints are available.

path = run.download_best_checkpoint("./checkpoints")
# → ./checkpoints/model_5000.pt