Run methods - Weights & Biases Documentation

Class wandb.apis.public.Run

method Run.beta_scan_history()

self,
keys: 'list[str] | None' = None,
page_size: 'int' = 1000,
min_step: 'int' = 0,
max_step: 'int | None' = None,
use_cache: 'bool' = True

Arguments

list[str] | None

int

int | None

bool

method Run.create()

Create a run for the given project. For most use cases, use wandb.init(). wandb.init() provides more robust logic for creating and updating runs. wandb.apis.public.Run.create is intended for specific scenarios such as creating runs in a “pending” state for jobs that may be unschedulable (for example, in a Kubernetes cluster with insufficient GPUs or high contention). These pending runs can later be resumed and tracked by W&B. Runs created with this method have limited functionality. Calling update() on a run created this way may not work as expected.

api: 'public.Api',
run_id: 'str | None' = None,
project: 'str | None' = None,
entity: 'str | None' = None,
state: "Literal['running', 'pending']" = 'running'

Arguments

public.Api

The W&B API instance.

str | None

Optional run ID. If not provided, a random ID will be generated.

str | None

Optional project name. Defaults to the project in API settings or “uncategorized”.

str | None

Optional entity (user or team) name.

Literal['running', 'pending']

Initial state of the run. Use “pending” for runs that will be resumed later, or “running” for immediate execution.

Returns

A Run object representing the created run.

Examples

Creating a pending run for later execution

import wandb

api = wandb.Api()

run_name = "my-pending-run"

run = Run.create(
    api=api,
    project="project",
    entity="entity",
    state="pending",
    run_id=run_name,
)

method Run.delete()

Delete the given run from the wandb backend.

self,
delete_artifacts: 'bool' = False

Arguments

bool

Whether to delete the artifacts associated with the run.

method Run.download_history_exports()

Download any parquet history files for the run to the provided directory.

self,
download_dir: 'pathlib.Path | str',
require_complete_history: 'bool' = True

Arguments

pathlib.Path | str

The directory to download the history files to.

bool

Whether to require the complete history to be downloaded. If true, and the run contains data that has not been exported to parquet files yet, an IncompleteRunHistoryError will be raised.

Returns

A DownloadHistoryResult.

Raises

If require_complete_history is True and the run contains data not yet exported to parquet files.

If the API request fails for reasons other than incomplete history.

method Run.file()

Return the path of a file with a given name in the artifact.

self,
name: 'str'

Arguments

str

name of requested file.

Returns

A File matching the name argument.

method Run.files()

Returns a Files object for all files in the run which match the given criteria. You can specify a list of exact file names to match, or a pattern to match against. If both are provided, the pattern will be ignored.

self,
names: 'list[str] | None' = None,
pattern: 'str | None' = None,
per_page: 'int' = 50

Arguments

list[str] | None

names of the requested files, if empty returns all files

str | None

Pattern to match when returning files from W&B. This pattern uses mySQL’s LIKE syntax, so matching all files that end with .json would be “%.json”. If both names and pattern are provided, a ValueError will be raised.

int

number of results per page.

Returns

A Files object, which is an iterator over File objects.

method Run.history()

Return sampled history metrics for a run. This is simpler and faster if you are ok with the history records being sampled.

self,
samples: 'int' = 500,
keys: 'list[str] | None' = None,
x_axis: 'str' = '_step',
pandas: 'bool' = True,
stream: "Literal['default', 'system']" = 'default'

Arguments

int

(int, optional) The number of samples to return

list[str] | None

(list, optional) Only return metrics for specific keys

str

(str, optional) Use this metric as the xAxis defaults to _step

bool

(bool, optional) Return a pandas dataframe

Literal['default', 'system']

(str, optional) “default” for metrics, “system” for machine metrics

Returns

pandas.DataFrame: If pandas=True returns a pandas.DataFrame of history metrics.

method Run.load()

Load run data using appropriate fragment based on lazy mode.

self,
force: 'bool' = False

Arguments

bool

If True, re-fetch the run data from the server, even if it is already loaded.

Returns

A dictionary of the run data.

Raises

If the run is not found, or the run data can not be loaded.

method Run.load_full_data()

Load full run data including heavy fields like config, systemMetrics, summaryMetrics. This method is useful when you initially used lazy=True for listing runs, but need access to the full data for specific runs.

self,
force: 'bool' = False

Arguments

bool

Force reload even if data is already loaded

Returns

The loaded run attributes

method Run.log_artifact()

Declare an artifact as output of a run.

self,
artifact: 'wandb.Artifact',
aliases: 'Collection[str] | None' = None,
tags: 'Collection[str] | None' = None

Arguments

wandb.Artifact

An artifact returned from wandb.Api().artifact(name).

Collection[str] | None

Aliases to apply to this artifact.

Collection[str] | None

(list, optional) Tags to apply to this artifact, if any.

Returns

A Artifact object.

method Run.logged_artifacts()

Fetches all artifacts logged by this run. Retrieves all output artifacts that were logged during the run. Returns a paginated result that can be iterated over or collected into a single list.

self,
per_page: 'int' = 100

Arguments

int

Number of artifacts to fetch per API request.

Returns

An iterable collection of all Artifact objects logged as outputs during this run.

Examples

import wandb
import tempfile

with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix=".txt") as tmp:
    tmp.write("This is a test artifact")
    tmp_path = tmp.name
run = wandb.init(project="artifact-example")
artifact = wandb.Artifact("test_artifact", type="dataset")
artifact.add_file(tmp_path)
run.log_artifact(artifact)
run.finish()

api = wandb.Api()

finished_run = api.run(f"{run.entity}/{run.project}/{run.id}")

for logged_artifact in finished_run.logged_artifacts():
    print(logged_artifact.name)

method Run.save()

Persist changes to the run object to the W&B backend.

self

method Run.scan_history()

Returns an iterable collection of all history records for a run.

self,
keys: 'list[str] | None' = None,
page_size: 'int' = 1000,
min_step: 'int' = 0,
max_step: 'int | None' = None,
use_cache: 'bool' = True

Arguments

list[str] | None

list of metrics to read from the run’s history. if no keys are provided then all metrics will be returned.

int

the number of history records to read at a time.

int

The minimum step to start reading history from (inclusive).

int | None

The maximum step to read history up to (exclusive).

bool

When set to True, checks the WANDB_CACHE_DIR for a run history. If the run history is not found in the cache, it will be downloaded from the server. If set to False, the run history will be downloaded every time.

Returns

A HistoryScan object, which can be iterator over to get history records.

method Run.stop()

Request that this run stop gracefully. This sets the run’s stop flag on the W&B backend, the same signal sent by the “Stop run” button in the W&B App UI. The process running the run picks the flag up through its regular heartbeat and shuts the run down gracefully, so this is safe for terminating remote runs (for example, runs on Kubernetes pods). Stopping is asynchronous: this method returns once the backend has flagged the run, not once the run terminates. Calling it again, or on a run that is no longer running, has no effect.

self

Raises

If the request fails.

Examples

import wandb

run = wandb.Api().run("entity/project/run_id")
run.stop()

method Run.to_html()

Generate HTML containing an iframe displaying this run.

self,
height: 'int' = 420,
hidden: 'bool' = False

Arguments

int

bool

method Run.update()

Persist changes to the run object to the wandb backend.

self

method Run.update_state()

Update the state of a run. Supported transitions:

to pending from running, failed, crashed, or preempted (e.g. to requeue a terminated or in-progress run)
to failed from pending or running (e.g. to mark a preempted or lost run as failed)

Sweep runs cannot have their state updated. See Run.state for the list of possible run states.

self,
state: 'str'

Arguments

str

The target run state. One of "pending" or "failed".

Returns

True if the state was successfully updated.

Raises

If the requested state transition is not allowed, or the server does not support this operation.

method Run.upload_file()

Upload a local file to W&B, associating it with this run.

self,
path: 'str',
root: 'str' = '.'

Arguments

str

Path to the file to upload. Can be absolute or relative.

str

The root path to save the file relative to. For example, if you want to have the file saved in the run as “my_dir/file.txt” and you’re currently in “my_dir” you would set root to ”../”. Defaults to current directory (”.”).

Returns

A File object representing the uploaded file.

method Run.use_artifact()

Declare an artifact as an input to a run.

self,
artifact: 'wandb.Artifact',
use_as: 'str | None' = None

Arguments

wandb.Artifact

An artifact returned from wandb.Api().artifact(name)

str | None

A string identifying how the artifact is used in the script. Used to easily differentiate artifacts used in a run, when using the beta wandb launch feature’s artifact swapping functionality.

Returns

An Artifact object.

method Run.used_artifacts()

Fetches artifacts explicitly used by this run. Retrieves only the input artifacts that were explicitly declared as used during the run, typically via run.use_artifact(). Returns a paginated result that can be iterated over or collected into a single list.

self,
per_page: 'int' = 100

Arguments

int

Number of artifacts to fetch per API request.

Returns

An iterable collection of Artifact objects explicitly used as inputs in this run.

Examples

import wandb

run = wandb.init(project="artifact-example")
run.use_artifact("test_artifact:latest")
run.finish()

api = wandb.Api()
finished_run = api.run(f"{run.entity}/{run.project}/{run.id}")
for used_artifact in finished_run.used_artifacts():
    print(used_artifact.name)
test_artifact

method Run.wait_until_finished()

Check the state of the run until it is finished.

self

​Class wandb.apis.public.Run

​method Run.beta_scan_history()

Arguments

​method Run.create()

Arguments

Returns

Examples

​method Run.delete()

Arguments

​method Run.download_history_exports()

Arguments

Returns

Raises

​method Run.file()

Arguments

Returns

​method Run.files()

Arguments

Returns

​method Run.history()

Arguments

Returns

​method Run.load()

Arguments

Returns

Raises

​method Run.load_full_data()

Arguments

Returns

​method Run.log_artifact()

Arguments

Returns

​method Run.logged_artifacts()

Arguments

Returns

Examples

​method Run.save()

​method Run.scan_history()

Arguments

Returns

​method Run.stop()

Raises

Examples

​method Run.to_html()

Arguments

​method Run.update()

​method Run.update_state()

Arguments

Returns

Raises

​method Run.upload_file()

Arguments

Returns

​method Run.use_artifact()

Arguments

Returns

​method Run.used_artifacts()

Arguments

Returns

Examples

​method Run.wait_until_finished()

Class wandb.apis.public.Run

method Run.beta_scan_history()

method Run.create()

method Run.delete()

method Run.download_history_exports()

method Run.file()

method Run.files()

method Run.history()

method Run.load()

method Run.load_full_data()

method Run.log_artifact()

method Run.logged_artifacts()

method Run.save()

method Run.scan_history()

method Run.stop()

method Run.to_html()

method Run.update()

method Run.update_state()

method Run.upload_file()

method Run.use_artifact()

method Run.used_artifacts()

method Run.wait_until_finished()