Run - Weights & Biases Documentation

`class` wandb.apis.public.Run

(service_api: 'ServiceApi',
entity: 'str',
project: 'str',
run_id: 'str',
attrs: 'Mapping | None' = None,
include_sweeps: 'bool' = False,
lazy: 'bool' = True,
api_key: 'str | None' = None)

A single run associated with an entity and project.

Args

service_api: Interface to the wandb-core service that performs W&B API calls for this run.
entity: The entity associated with the run.
project: The project associated with the run.
run_id: The unique identifier for the run.
attrs: The attributes of the run.
include_sweeps: Whether to include sweeps in the run.
lazy:
api_key:

Attributes

tags ([str]): a list of tags associated with the run
url (str): the url of this run
id (str): unique identifier for the run (defaults to eight characters)
name (str): the name of the run
state (str): one of: running, finished, crashed, killed, preempting, preempted
config (dict): a dict of hyperparameters associated with the run
created_at (str): ISO timestamp when the run was started
system_metrics (dict): the latest system metrics recorded for the run
summary (dict): A mutable dict-like property that holds the current summary. Calling update will persist any changes.
project (str): the project associated with the run
entity (str): the name of the entity associated with the run
project_internal_id (int): the internal id of the project
user (str): the name of the user who created the run
path (str): Unique identifier [entity]/[project]/[run_id]
notes (str): Notes about the run
read_only (boolean): Whether the run is editable
history_keys (str): History metric keys logged with wandb.Run.log({"key": "value"})
metadata (str): Metadata about the run from wandb-metadata.json

Properties

`property` config

Get run config. Auto-loads full data if in lazy mode.

`property` entity

The entity associated with the run.

`property` id

The unique identifier for the run.

`property` lastHistoryStep

Returns the last step logged in the run’s history.

`property` metadata

Metadata about the run from wandb-metadata.json. Metadata includes the run’s description, tags, start time, memory usage and more.

`property` name

The name of the run.

`property` path

The path of the run. The path is a list containing the entity, project, and run_id.

`property` rawconfig

Get raw run config including internal keys. Auto-loads full data if in lazy mode.

`property` state

The state of the run. The following table describes the possible states a run can be in:

State	Description
Crashed	Run stopped sending heartbeats in the internal process, which can happen if the machine crashes.
Failed	Run ended with a non-zero exit status.
Finished	Run ended and fully synced data, or called `wandb.Run.finish()`.
Killed	Run was forcibly stopped before it could finish.
Running	Run is still running and has recently sent a heartbeat.
Pending	Run is scheduled but not yet started (common in sweeps and Launch jobs).

`property` storage_id

The unique storage identifier for the run.

`property` summary

Get run summary metrics. Auto-loads full data if in lazy mode.

`property` summary_metrics

Get run summary metrics. Auto-loads full data if in lazy mode.

`property` sweep

The sweep associated with this run. Loads sweep data if include_sweeps is False.

`property` sweep_name

Get sweep name. Always available since sweepName is in lightweight fragment.

`property` system_metrics

Get run system metrics. Auto-loads full data if in lazy mode.

`property` url

The URL of the run. The run URL is generated from the entity, project, and run_id. For SaaS users, it takes the form of https://wandb.ai/entity/project/run_id.

`property` username

This API is deprecated. Use entity instead.

Methods

`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

keys:
page_size:
min_step:
max_step:
use_cache:

`method` Run.create()

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

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.

Arguments

api: The W&B API instance.
run_id: Optional run ID. If not provided, a random ID will be generated.
project: Optional project name. Defaults to the project in API settings or “uncategorized”.
entity: Optional entity (user or team) name.
state: Initial state of the run. Use “pending” for runs that will be resumed later, or “running” for immediate execution.

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()

self,
delete_artifacts: 'bool' = False

Delete the given run from the wandb backend.

Arguments

delete_artifacts: Whether to delete the artifacts associated with the run.

`method` Run.download_history_exports()

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

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

Arguments

download_dir: The directory to download the history files to.
require_complete_history: 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.

Raises

IncompleteRunHistoryError: If require_complete_history is True and the run contains data not yet exported to parquet files.
WandbApiFailedError: If the API request fails for reasons other than incomplete history.

`method` Run.file()

self,
name: 'str'

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

Arguments

name: name of requested file.

`method` Run.files()

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

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.

Arguments

names: names of the requested files, if empty returns all files
pattern: 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.
per_page: number of results per page.

`method` Run.history()

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

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

Arguments

samples: (int, optional) The number of samples to return
keys: (list, optional) Only return metrics for specific keys
x_axis: (str, optional) Use this metric as the xAxis defaults to _step
pandas: (bool, optional) Return a pandas dataframe
stream: (str, optional) “default” for metrics, “system” for machine metrics

`method` Run.load()

self,
force: 'bool' = False

Load run data using appropriate fragment based on lazy mode.

Arguments

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

Raises

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

`method` Run.load_full_data()

self,
force: 'bool' = False

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.

Arguments

force: Force reload even if data is already loaded

`method` Run.log_artifact()

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

Declare an artifact as output of a run.

Arguments

artifact: An artifact returned from wandb.Api().artifact(name).
aliases: Aliases to apply to this artifact.
tags: (list, optional) Tags to apply to this artifact, if any.

`method` Run.logged_artifacts()

self,
per_page: 'int' = 100

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.

Arguments

per_page: Number of artifacts to fetch per API request.

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()

self

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

`method` Run.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

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

Arguments

keys: list of metrics to read from the run’s history. if no keys are provided then all metrics will be returned.
page_size: the number of history records to read at a time.
min_step: The minimum step to start reading history from (inclusive).
max_step: The maximum step to read history up to (exclusive).
use_cache: 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.

`method` Run.stop()

self

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.

Raises

wandb.Error: If the request fails.

Examples

import wandb

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

`method` Run.to_html()

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

Generate HTML containing an iframe displaying this run.

Arguments

height:
hidden:

`method` Run.update()

self

Persist changes to the run object to the wandb backend.

`method` Run.update_state()

self,
state: 'str'

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.

Arguments

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

Raises

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

`method` Run.upload_file()

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

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

Arguments

path: Path to the file to upload. Can be absolute or relative.
root: 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 (”.“).

`method` Run.use_artifact()

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

Declare an artifact as an input to a run.

Arguments

artifact: An artifact returned from wandb.Api().artifact(name)
use_as: 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.

`method` Run.used_artifacts()

self,
per_page: 'int' = 100

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.

Arguments

per_page: Number of artifacts to fetch per API request.

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()

self

Check the state of the run until it is finished.

​class wandb.apis.public.Run

​Args

​Attributes

​Properties

​property config

​property entity

​property id

​property lastHistoryStep

​property metadata

​property name

​property path

​property rawconfig

​property state

​property storage_id

​property summary

​property summary_metrics

​property sweep

​property sweep_name

​property system_metrics

​property url

​property username

​Methods

​method Run.beta_scan_history()

Arguments

​method Run.create()

Arguments

Examples

​method Run.delete()

Arguments

​method Run.download_history_exports()

Arguments

Raises

​method Run.file()

Arguments

​method Run.files()

Arguments

​method Run.history()

Arguments

​method Run.load()

Arguments

Raises

​method Run.load_full_data()

Arguments

​method Run.log_artifact()

Arguments

​method Run.logged_artifacts()

Arguments

Examples

​method Run.save()

​method Run.scan_history()

Arguments

​method Run.stop()

Raises

Examples

​method Run.to_html()

Arguments

​method Run.update()

​method Run.update_state()

Arguments

Raises

​method Run.upload_file()

Arguments

​method Run.use_artifact()

Arguments

​method Run.used_artifacts()

Arguments

Examples

​method Run.wait_until_finished()

`class` wandb.apis.public.Run

Args

Attributes

Properties

`property` config

`property` entity

`property` id

`property` lastHistoryStep

`property` metadata

`property` name

`property` path

`property` rawconfig

`property` state

`property` storage_id

`property` summary

`property` summary_metrics

`property` sweep

`property` sweep_name

`property` system_metrics

`property` url

`property` username

Methods

`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()