Run - Weights & Biases Documentation

Class wandb.apis.public.Run

A single run associated with an entity and project.

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

Args

ServiceApi

Interface to the wandb-core service that performs W&B API calls for this run.

str

The entity associated with the run.

str

The project associated with the run.

str

The unique identifier for the run.

Mapping | None

The attributes of the run.

bool

Whether to include sweeps in the run.

bool

No description provided.

str | None

No description provided.

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

dict[str, Any]

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

str

The entity associated with the run.

str

The unique identifier for the run.

int

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

dict[str, Any] | None

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

str | None

The name of the run.

list[str]

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

dict[str, Any]

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

str

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

str

The unique storage identifier for the run.

HTTPSummary

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

dict[str, Any]

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

public.Sweep | None

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

str | None

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

dict[str, Any]

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

str

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.

str

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

list[str] | None

No description provided.

int

No description provided.

int

No description provided.

int | None

No description provided.

bool

No description provided.

method Run.console_logs()

self, *,
per_page: 'int' = 1000,
last: 'int | None' = None

Return the run’s captured console output. While a run is running, W&B captures what its process writes to stdout and stderr and records it as the run’s console log — the same log shown in the “Logs” tab of the run page in the W&B App. This reads that log back, for finished and still-running runs alike.

Arguments

int

Number of lines to fetch per request when reading the log from the beginning. Ignored when last is given.

int | None

If set, fetch only the last N lines of the log in a single request — useful for checking on a live run or diagnosing a crash. The backend caps how many lines one request returns, so a larger tail comes back truncated to the newest lines.

Raises

CommError: When iterating, if a request fails. Reading the log from the beginning requires W&B server 0.77 or newer; on older servers, read the last N lines instead.

Examples

import wandb

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

# Read the whole log, oldest line first.
for line in run.console_logs():
    print(line.content)

# Read only the last 100 lines.
for line in run.console_logs(last=100):
    print(line.timestamp, line.content)

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

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.

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

bool

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

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.

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

str

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

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.

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

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

method Run.load()

self,
force: 'bool' = False

Load run data using appropriate fragment based on lazy mode.

Arguments

bool

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

bool

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

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.

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

int

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

list[str] | None

List of metrics to read from the run’s history. The scan only returns rows that contain all of the requested keys. If the keys were logged at different steps, use separate calls for each key or omit this argument. If no keys are provided, all metrics are 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.

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

int

No description provided.

bool

No description provided.

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

str

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

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 (”.“).

method Run.use_artifact()

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

Declare an artifact as an input to a run.

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.

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

int

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

​Methods

​method Run.beta_scan_history()

Arguments

​method Run.console_logs()

Arguments

Raises

Examples

​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

Methods

method Run.beta_scan_history()

method Run.console_logs()

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