You can delete W&B runs programmatically, but it’s not a straightforward run.delete() call; instead, you’re actually archiving them, and the actual deletion is a background process.
Let’s look at how to manage your Weights & Biases runs via the API. We’ll cover creating, updating, and, yes, "deleting" runs, and then how to query them effectively.
Creating a Run
The core of W&B’s programmatic interface is the wandb.init() call. When you run this in your script, it starts a new "run" on the W&B servers.
import wandb
# Initialize a run
run = wandb.init(project="my-project", job_type="training")
print(f"Run initialized: {run.url}")
This run object is your handle to the active W&B session. You can log metrics, save artifacts, and configure the run through this object.
Logging Data and Artifacts
Once a run is initialized, you can log various types of data:
# Log metrics
for i in range(100):
run.log({"accuracy": i / 100, "loss": 1 - (i / 100)})
# Log a file as an artifact
with open("model.pth", "w") as f:
f.write("dummy model weights")
artifact = wandb.Artifact("model-weights", type="model")
artifact.add_file("model.pth")
run.log_artifact(artifact)
Artifacts are W&B’s way of versioning and tracking datasets, models, and other files.
Updating Run Information
You can update metadata associated with a run after it’s started, or even after it’s finished.
# Update run name and description
run.name = "experiment-v1"
run.summary["final_accuracy"] = 0.95
run.finish() # Finish the run
run.finish() signals that the run is complete and stops logging.
"Deleting" Runs (Archiving)
The term "delete" in W&B’s API context usually means archiving a run. Archiving hides the run from your default project views and stops it from counting towards your project’s storage limits. The actual data is purged after a grace period.
You can archive a run using the wandb.Api() client:
from wandb.sdk.wandb_api import Api
api = Api()
project = api.project("my-project")
run_to_archive = project.run("run_id_to_archive") # Replace with actual run ID
# Archive the run
run_to_archive.archive()
print(f"Run {run_to_archive.id} archived.")
To find the run_id_to_archive, you’d typically query for runs first.
Querying Runs
The wandb.Api() client is your tool for inspecting your W&B data. You can fetch runs, filter them, and retrieve their details.
from wandb.sdk.wandb_api import Api
api = Api()
project = api.project("my-project")
# Get all runs in the project
all_runs = project.runs()
for r in all_runs:
print(f"Run ID: {r.id}, Name: {r.name}, State: {r.state}")
# Filter runs by state (e.g., only finished runs)
finished_runs = project.runs(filters={"state": "finished"})
for r in finished_runs:
print(f"Finished Run: {r.name} ({r.id})")
# Filter by a specific metric or tag
# Note: Complex filtering often requires iterating or using the GraphQL API for efficiency.
# For simple cases, you can filter the Python list:
recent_high_acc_runs = [
r for r in project.runs(filters={"state": "finished"})
if r.summary.get("final_accuracy", 0) > 0.9
]
for r in recent_high_acc_runs:
print(f"High Accuracy Run: {r.name} ({r.summary['final_accuracy']})")
# Fetching a specific run by ID
specific_run = api.run("my-project/run_id_to_fetch")
print(f"Fetched run: {specific_run.name}")
print(f"Metrics: {specific_run.summary}")
The filters argument for project.runs() is powerful, accepting dictionaries that map to W&B’s internal query language. Common filters include state, job_type, name, and tags. For more complex queries, especially involving logged metrics or artifact versions, you’d typically use W&B’s GraphQL API directly, which the wandb.Api client uses under the hood.
The run.archive() method doesn’t immediately destroy data. Instead, it flags the run for deletion. W&B has a background process that handles the actual data purging based on your organization’s retention policies. If you need to force a deletion for immediate compliance or cleanup, you’d typically need to contact W&B support or use their GraphQL API with specific deleteRun mutations, which are generally reserved for administrative use.
The next concept you’ll likely encounter is managing W&B artifacts and their lineage across multiple runs.