Run

Description

A single run associated with an entity and project.

Args

• client: Legacy GraphQL client retained for API compatibility.
• 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: Whether to lazily load run data or fetch full data immediately.
• service_api: Optional ServiceApi instance for making additional API calls.

Properties

property state

The state of the run. Can be one of: Finished, Failed, Crashed, or Running.

property entity

The entity associated with the run.

property username

This API is deprecated. Use entity instead.

property storage_id

The unique storage identifier for the run.

property id

The unique identifier for the run.

property name

The name of the run.

property config

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

property summary

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

property system_metrics

Get run system 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 rawconfig

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

property sweep_name

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

property path

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

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 metadata

Metadata about the run from wandb-metadata.json.

Metadata includes the run’s description, tags, start time, memory usage and more.

property lastHistoryStep

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

Methods

method 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

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

This function is still in development and may not work as expected. It uses wandb-core to read history from a run’s exported parquet history locally.

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 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 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 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 display

self, height=420, hidden=False

Display this object in jupyter.

Arguments

• height:
• hidden:

method 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 file

self,
name: 'str'

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

Arguments

• name: name of requested file.

method 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 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 load

self,
force: 'bool' = False

Load run data using appropriate fragment based on lazy mode.

Arguments

• force:

method 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 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 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 save

self

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

method scan_history

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

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

Arguments

• keys: only fetch these keys, and only fetch rows that have all of keys defined.
• page_size: size of pages to fetch from the api.
• min_step: the minimum number of pages to scan at a time.
• max_step: the maximum number of pages to scan at a time.

Examples

Export all the loss values for an example run

run = api.run("entity/project-name/run-id")
history = run.scan_history(keys=["Loss"])
losses = [row["Loss"] for row in history]

method update

self

Persist changes to the run object to the wandb backend.

method update_state

self,
state: "Literal['pending']"

Update the state of a run.

Allows transitioning runs from ‘failed’ or ‘crashed’ to ‘pending’.

Arguments

• state: The target run state. Only "pending" is supported.

Raises

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

method 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 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 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 wait_until_finished

self

Check the state of the run until it is finished.