Runs

The runs API covers the public run lifecycle surface: identifiers, submission configuration, run handles, metadata, and helper functions for querying, collecting, and deleting runs.

Identifiers and Type Aliases

rush.runs.RunID = rush.runs.RunID

String identifier for a Rush run.

type rush.runs.RunStatus = Literal['pending', 'running', 'done', 'error', 'cancelled', 'draft']

All self-explanatory: pending runs are queued for submission to a target.

type rush.runs.Target = Literal['Bullet', 'Bullet2', 'Bullet3', 'Gadi', 'Setonix']

Valid values for the target field of RunSpec.

type rush.runs.StorageUnit = Literal['KB', 'MB', 'GB']

Valid values for the storage_units field of RunSpec.

Submission Types

class rush.runs.RunSpec(target=None, walltime=None, storage=10, storage_units='MB', cpus=None, gpus=None, nodes=None)[source]

The run specification: configuration for the target and resources of a run.

Parameters:

  • target (Target | None)

  • walltime (int | None)

  • storage (int | None)

  • storage_units (StorageUnit | None)

  • cpus (int | None)

  • gpus (int | None)

  • nodes (int | None)

cpus: int | None = None

The number of CPUs for the run. Default is module-specific.

gpus: int | None = None

The number of GPUs for the run. Default is module-specific.

nodes: int | None = None

The number of nodes for the run. Only relevant for supercomputer targets. Default is module-specific.

storage: int | None = 10

Max storage in the specified storage units for the run.

storage_units: StorageUnit | None = 'MB'

The storage units for the run.

target: Target | None = None

The Rush-specified hardware that the run will be submitted to. By default, randomly chooses a cloud compute “Bullet” node of the available ones.

walltime: int | None = None

Max walltime in minutes for the run.

class rush.runs.RunOpts(name=None, description=None, tags=None, email=None)[source]

The description currently doesn’t show up anywhere. The tags will also show up in the Rush UI and will (eventually) allow for run searching and filtering. The email flag, if set to True, will cause an email to be sent to you upon run completion.

Parameters:

  • name (str | None)

  • description (str | None)

  • tags (list[str] | None)

  • email (bool | None)

description: str | None = None
email: bool | None = None
name: str | None = None

Shows up as the name (i.e. title) of the run in the Rush UI.

tags: list[str] | None = None

Run Handles and Metadata

class rush.runs.Run(id, result_type)[source]

Handle to a submitted Rush job.

Parameters:

  • id (RunID)

  • result_type (type[R])

collect(max_wait_time=3600)[source]
Parameters:

max_wait_time (int)

Return type:

R

fetch(**kwargs)[source]
Parameters:

kwargs (Any)

Return type:

Any

save(**kwargs)[source]
Parameters:

kwargs (Any)

Return type:

Any

property id: RunID
class rush.runs.RunInfo(id, created_at, updated_at, status, deleted_at=None, name=None, description=None, tags=None, result=None, stdout=None, trace=None, walltime=None, sus=None)[source]

Print it out to see a nicely-formatted summary of a run!

Parameters:

  • id (RunID)

  • created_at (str)

  • updated_at (str)

  • status (str)

  • deleted_at (str | None)

  • name (str | None)

  • description (str | None)

  • tags (list[str] | None)

  • result (dict[str, Any] | None)

  • stdout (str | None)

  • trace (dict[str, Any] | None)

  • walltime (int | float | None)

  • sus (dict[str, int | float] | None)

created_at: str
deleted_at: str | None = None
description: str | None = None
id: RunID
name: str | None = None
result: dict[str, Any] | None = None
status: str
stdout: str | None = None
sus: dict[str, int | float] | None = None
tags: list[str] | None = None
trace: dict[str, Any] | None = None
updated_at: str
walltime: int | float | None = None
class rush.runs.RunError(message, trace='')[source]

Base class for errors raised while collecting a Rush run.

Parameters:

  • message (str)

  • trace (str)

message: str
trace: str = ''
class rush.runs.RunBackendError(message, trace='')[source]

Run failed due to Rush backend, infrastructure, or orchestration issues.

Parameters:

  • message (str)

  • trace (str)

class rush.runs.RunModuleError(message, trace='')[source]

Run failed inside the module/application layer.

Parameters:

  • message (str)

  • trace (str)

Run Queries and Collection

rush.runs.fetch_runs(*, name=None, name_contains=None, status=None, tags=None, limit=None)[source]

Query runs and return their IDs.

Parameters:

  • name (str | None) – Filter by exact run name (case-insensitive).

  • name_contains (str | None) – Filter by runs whose name contains this substring.

  • status (RunStatus | list[RunStatus] | None) – Filter by status. Can be a single status or a list of statuses.

  • tags (list[str] | None) – Filter by tags. Returns runs that have ALL specified tags.

  • limit (int | None) – Maximum number of runs to return. If None, returns all matching runs.

Returns:

A list of run IDs matching the filters.

Return type:

list[RunID]

rush.runs.fetch_run_info(run_id)[source]

Fetch all info for a run by ID.

Returns None if the run doesn’t exist.

Parameters:

run_id (str | RunID)

Return type:

RunInfo | None

rush.runs.collect_run(run_id, max_wait_time=3600)[source]

Wait until the run finishes and return its outputs.

Raises:

  • RunBackendError – If the run times out, is cancelled, or the Rush backend fails to execute it successfully.

  • RunModuleError – If the module fails inside the module/application layer.

Parameters:

  • run_id (str | RunID)

  • max_wait_time (int)

rush.runs.delete_run(run_id)[source]

Delete a run by ID.

Parameters:

run_id (str | RunID)

Return type:

None