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

# Run methods

## <Badge color="yellow" size="lg" shape="rounded">Class</Badge> wandb.apis.public.Run

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.beta\_scan\_history()

```python theme={null}
self,
keys: 'list[str] | None' = None,
page_size: 'int' = 1000,
min_step: 'int' = 0,
max_step: 'int | None' = None,
use_cache: 'bool' = True
```

##### Arguments

<ResponseField name="keys" type="list[str] | None" />

<ResponseField name="page_size" type="int" />

<ResponseField name="min_step" type="int" />

<ResponseField name="max_step" type="int | None" />

<ResponseField name="use_cache" type="bool" />

## <Badge color="blue" size="lg" shape="rounded">method</Badge> 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.

```python theme={null}
api: 'public.Api',
run_id: 'str | None' = None,
project: 'str | None' = None,
entity: 'str | None' = None,
state: "Literal['running', 'pending']" = 'running'
```

##### Arguments

<ResponseField name="api" type="public.Api">
  The W\&B API instance.
</ResponseField>

<ResponseField name="run_id" type="str | None">
  Optional run ID. If not provided, a random ID will be generated.
</ResponseField>

<ResponseField name="project" type="str | None">
  Optional project name. Defaults to the project in API settings or "uncategorized".
</ResponseField>

<ResponseField name="entity" type="str | None">
  Optional entity (user or team) name.
</ResponseField>

<ResponseField name="state" type="Literal['running', 'pending']">
  Initial state of the run. Use "pending" for runs that will be resumed later, or "running" for immediate execution.
</ResponseField>

##### Returns

A Run object representing the created run.

##### Examples

Creating a pending run for later execution

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

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.delete()

Delete the given run from the wandb backend.

```python theme={null}
self,
delete_artifacts: 'bool' = False
```

##### Arguments

<ResponseField name="delete_artifacts" type="bool">
  Whether to delete the artifacts associated with the run.
</ResponseField>

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.download\_history\_exports()

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

```python theme={null}
self,
download_dir: 'pathlib.Path | str',
require_complete_history: 'bool' = True
```

##### Arguments

<ResponseField name="download_dir" type="pathlib.Path | str">
  The directory to download the history files to.
</ResponseField>

<ResponseField name="require_complete_history" type="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.
</ResponseField>

##### Returns

A DownloadHistoryResult.

##### Raises

<ResponseField name="IncompleteRunHistoryError">
  If require\_complete\_history is True and the run contains data not yet exported to parquet files.
</ResponseField>

<ResponseField name="WandbApiFailedError">
  If the API request fails for reasons other than incomplete history.
</ResponseField>

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.file()

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

```python theme={null}
self,
name: 'str'
```

##### Arguments

<ResponseField name="name" type="str">
  name of requested file.
</ResponseField>

##### Returns

A `File` matching the name argument.

## <Badge color="blue" size="lg" shape="rounded">method</Badge> 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.

```python theme={null}
self,
names: 'list[str] | None' = None,
pattern: 'str | None' = None,
per_page: 'int' = 50
```

##### Arguments

<ResponseField name="names" type="list[str] | None">
  names of the requested files, if empty returns all files
</ResponseField>

<ResponseField name="pattern" type="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.
</ResponseField>

<ResponseField name="per_page" type="int">
  number of results per page.
</ResponseField>

##### Returns

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

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.history()

Return sampled history metrics for a run.

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

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

##### Arguments

<ResponseField name="samples" type="int">
  (int, optional) The number of samples to return
</ResponseField>

<ResponseField name="keys" type="list[str] | None">
  (list, optional) Only return metrics for specific keys
</ResponseField>

<ResponseField name="x_axis" type="str">
  (str, optional) Use this metric as the xAxis defaults to \_step
</ResponseField>

<ResponseField name="pandas" type="bool">
  (bool, optional) Return a pandas dataframe
</ResponseField>

<ResponseField name="stream" type="Literal['default', 'system']">
  (str, optional) "default" for metrics, "system" for machine metrics
</ResponseField>

##### Returns

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

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.load()

Load run data using appropriate fragment based on lazy mode.

```python theme={null}
self,
force: 'bool' = False
```

##### Arguments

<ResponseField name="force" type="bool">
  If True, re-fetch the run data from the server, even if it is already loaded.
</ResponseField>

##### Returns

A dictionary of the run data.

##### Raises

<ResponseField name="RunNotFoundError">
  If the run is not found, or the run data can not be loaded.
</ResponseField>

## <Badge color="blue" size="lg" shape="rounded">method</Badge> 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.

```python theme={null}
self,
force: 'bool' = False
```

##### Arguments

<ResponseField name="force" type="bool">
  Force reload even if data is already loaded
</ResponseField>

##### Returns

The loaded run attributes

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.log\_artifact()

Declare an artifact as output of a run.

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

##### Arguments

<ResponseField name="artifact" type="wandb.Artifact">
  An artifact returned from `wandb.Api().artifact(name)`.
</ResponseField>

<ResponseField name="aliases" type="Collection[str] | None">
  Aliases to apply to this artifact.
</ResponseField>

<ResponseField name="tags" type="Collection[str] | None">
  (list, optional) Tags to apply to this artifact, if any.
</ResponseField>

##### Returns

A `Artifact` object.

## <Badge color="blue" size="lg" shape="rounded">method</Badge> 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.

```python theme={null}
self,
per_page: 'int' = 100
```

##### Arguments

<ResponseField name="per_page" type="int">
  Number of artifacts to fetch per API request.
</ResponseField>

##### Returns

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

##### Examples

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

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.save()

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

```python theme={null}
self
```

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.scan\_history()

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

```python theme={null}
self,
keys: 'list[str] | None' = None,
page_size: 'int' = 1000,
min_step: 'int' = 0,
max_step: 'int | None' = None,
use_cache: 'bool' = True
```

##### Arguments

<ResponseField name="keys" type="list[str] | None">
  list of metrics to read from the run's history. if no keys are provided then all metrics will be returned.
</ResponseField>

<ResponseField name="page_size" type="int">
  the number of history records to read at a time.
</ResponseField>

<ResponseField name="min_step" type="int">
  The minimum step to start reading history from (inclusive).
</ResponseField>

<ResponseField name="max_step" type="int | None">
  The maximum step to read history up to (exclusive).
</ResponseField>

<ResponseField name="use_cache" type="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.
</ResponseField>

##### Returns

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

## <Badge color="blue" size="lg" shape="rounded">method</Badge> 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.

```python theme={null}
self
```

##### Raises

<ResponseField name="`wandb.Error`">
  If the request fails.
</ResponseField>

##### Examples

```python theme={null}
import wandb

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

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.to\_html()

Generate HTML containing an iframe displaying this run.

```python theme={null}
self,
height: 'int' = 420,
hidden: 'bool' = False
```

##### Arguments

<ResponseField name="height" type="int" />

<ResponseField name="hidden" type="bool" />

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.update()

Persist changes to the run object to the wandb backend.

```python theme={null}
self
```

## <Badge color="blue" size="lg" shape="rounded">method</Badge> 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.

```python theme={null}
self,
state: 'str'
```

##### Arguments

<ResponseField name="state" type="str">
  The target run state. One of `"pending"` or `"failed"`.
</ResponseField>

##### Returns

`True` if the state was successfully updated.

##### Raises

<ResponseField name="`wandb.Error`">
  If the requested state transition is not allowed, or the server does not support this operation.
</ResponseField>

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.upload\_file()

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

```python theme={null}
self,
path: 'str',
root: 'str' = '.'
```

##### Arguments

<ResponseField name="path" type="str">
  Path to the file to upload. Can be absolute or relative.
</ResponseField>

<ResponseField name="root" type="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 (".").
</ResponseField>

##### Returns

A `File` object representing the uploaded file.

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.use\_artifact()

Declare an artifact as an input to a run.

```python theme={null}
self,
artifact: 'wandb.Artifact',
use_as: 'str | None' = None
```

##### Arguments

<ResponseField name="artifact" type="wandb.Artifact">
  An artifact returned from `wandb.Api().artifact(name)`
</ResponseField>

<ResponseField name="use_as" type="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.
</ResponseField>

##### Returns

An `Artifact` object.

## <Badge color="blue" size="lg" shape="rounded">method</Badge> 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.

```python theme={null}
self,
per_page: 'int' = 100
```

##### Arguments

<ResponseField name="per_page" type="int">
  Number of artifacts to fetch per API request.
</ResponseField>

##### Returns

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

##### Examples

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

## <Badge color="blue" size="lg" shape="rounded">method</Badge> Run.wait\_until\_finished()

Check the state of the run until it is finished.

```python theme={null}
self
```