> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-feat-cli-docs-generator.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run

export const GitHubLink = ({url}) => <a href={url} target="_blank" rel="noopener noreferrer" className="github-source-link">
    <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
      <path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0024 12c0-6.63-5.37-12-12-12z" />
    </svg>
    GitHub source
  </a>;

<GitHubLink url="https://github.com/wandb/wandb/blob/main/wandb/apis/public/runs.py" />

## <kbd>class</kbd> `Run`

A single run associated with an entity and project.

### <kbd>method</kbd> `Run.__init__`

```python theme={null}
__init__(
    client: 'RetryingClient',
    entity: 'str',
    project: 'str',
    run_id: 'str',
    attrs: 'Mapping | None' = None,
    include_sweeps: 'bool' = True,
    lazy: 'bool' = True
)
```

**Args:**

* `client`:  The W\&B API client.
* `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.

**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):  Keys of the history metrics that have been logged with `wandb.log({"key":  "value"})`
* `metadata` (str):  Metadata about the run from wandb-metadata.json

Initialize a Run object.

Run is always initialized by calling api.runs() where api is an instance of wandb.Api.

***

### <kbd>property</kbd> Run.config

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

***

### <kbd>property</kbd> Run.entity

The entity associated with the run.

***

### <kbd>property</kbd> Run.id

The unique identifier for the run.

***

### <kbd>property</kbd> Run.lastHistoryStep

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

***

### <kbd>property</kbd> Run.metadata

Metadata about the run from wandb-metadata.json.

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

***

### <kbd>property</kbd> Run.name

The name of the run.

***

### <kbd>property</kbd> Run.path

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

***

### <kbd>property</kbd> Run.rawconfig

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

***

### <kbd>property</kbd> Run.state

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

***

### <kbd>property</kbd> Run.storage\_id

The unique storage identifier for the run.

***

### <kbd>property</kbd> Run.summary

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

***

### <kbd>property</kbd> Run.summary\_metrics

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

***

### <kbd>property</kbd> Run.sweep\_name

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

***

### <kbd>property</kbd> Run.system\_metrics

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

***

### <kbd>property</kbd> Run.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`.

***

### <kbd>property</kbd> Run.username

This API is deprecated. Use `entity` instead.

***

### <kbd>classmethod</kbd> `Run.create`

```python theme={null}
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.

***

### <kbd>method</kbd> `Run.delete`

```python theme={null}
delete(delete_artifacts=False)
```

Delete the given run from the wandb backend.

**Args:**

* `delete_artifacts` (bool, optional):  Whether to delete the artifacts  associated with the run.

***

### <kbd>method</kbd> `Run.file`

```python theme={null}
file(name)
```

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

**Args:**

* `name` (str):  name of requested file.

**Returns:**
A `File` matching the name argument.

***

### <kbd>method</kbd> `Run.files`

```python theme={null}
files(
    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.

**Args:**

* `names` (list):  names of the requested files, if empty returns all files
* `pattern` (str, optional):  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` (int):  number of results per page.

**Returns:**
A `Files` object, which is an iterator over `File` objects.

***

### <kbd>method</kbd> `Run.history`

```python theme={null}
history(samples=500, keys=None, x_axis='_step', pandas=True, stream='default')
```

Return sampled history metrics for a run.

This is simpler and faster if you are ok with the history records being sampled.

**Args:**

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

**Returns:**

* `pandas.DataFrame`:  If pandas=True returns a `pandas.DataFrame` of history  metrics.
* `list of dicts`:  If pandas=False returns a list of dicts of history metrics.

***

### <kbd>method</kbd> `Run.load`

```python theme={null}
load(force=False)
```

Load run data using appropriate fragment based on lazy mode.

***

### <kbd>method</kbd> `Run.load_full_data`

```python theme={null}
load_full_data(force: 'bool' = False) → dict[str, Any]
```

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.

**Args:**

* `force`:  Force reload even if data is already loaded

**Returns:**
The loaded run attributes

***

### <kbd>method</kbd> `Run.log_artifact`

```python theme={null}
log_artifact(
    artifact: 'wandb.Artifact',
    aliases: 'Collection[str] | None' = None,
    tags: 'Collection[str] | None' = None
)
```

Declare an artifact as output of a run.

**Args:**

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

**Returns:**
A `Artifact` object.

***

### <kbd>method</kbd> `Run.logged_artifacts`

```python theme={null}
logged_artifacts(per_page: 'int' = 100) → public.RunArtifacts
```

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.

**Args:**

* `per_page`:  Number of artifacts to fetch per API request.

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

**Example:**

```python theme={null}
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)
```

***

### <kbd>method</kbd> `Run.save`

```python theme={null}
save()
```

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

***

### <kbd>method</kbd> `Run.scan_history`

```python theme={null}
scan_history(keys=None, page_size=1000, min_step=None, max_step=None)
```

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

**Args:**

* `keys` (\[str], optional):  only fetch these keys, and only fetch rows that have all of keys defined.
* `page_size` (int, optional):  size of pages to fetch from the api.
* `min_step` (int, optional):  the minimum number of pages to scan at a time.
* `max_step` (int, optional):  the maximum number of pages to scan at a time.

**Returns:**
An iterable collection over history records (dict).

**Example:**
Export all the loss values for an example run

```python theme={null}
run = api.run("entity/project-name/run-id")
history = run.scan_history(keys=["Loss"])
losses = [row["Loss"] for row in history]
```

***

### <kbd>method</kbd> `Run.to_html`

```python theme={null}
to_html(height=420, hidden=False)
```

Generate HTML containing an iframe displaying this run.

***

### <kbd>method</kbd> `Run.update`

```python theme={null}
update()
```

Persist changes to the run object to the wandb backend.

***

### <kbd>method</kbd> `Run.upload_file`

```python theme={null}
upload_file(path, root='.')
```

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

**Args:**

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

***

### <kbd>method</kbd> `Run.use_artifact`

```python theme={null}
use_artifact(artifact, use_as=None)
```

Declare an artifact as an input to a run.

**Args:**

* `artifact` (`Artifact`):  An artifact returned from  `wandb.Api().artifact(name)`
* `use_as` (string, optional):  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.

***

### <kbd>method</kbd> `Run.used_artifacts`

```python theme={null}
used_artifacts(per_page: 'int' = 100) → public.RunArtifacts
```

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.

**Args:**

* `per_page`:  Number of artifacts to fetch per API request.

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

**Example:**

```python theme={null}
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
```

***

### <kbd>method</kbd> `Run.wait_until_finished`

```python theme={null}
wait_until_finished()
```

Check the state of the run until it is finished.