1 - Api
Training and fine-tuning models is done elsewhere in the W&B Python SDK. Use the Public API for querying and managing data after it has been logged to W&B.
class Api
Used for querying the W&B server.
Examples:
method Api.__init__
__init__(
overrides: Optional[Dict[str, Any]] = None,
timeout: Optional[int] = None,
api_key: Optional[str] = None
) → None
Initialize the API.
Args:
overrides: You can set base_url if you areusing a W&B server other than https: //api.wandb.ai. You can also set defaults for entity, project, and run.timeout: HTTP timeout in seconds for API requests. If not specified, the default timeout will be used.api_key: API key to use for authentication. If not provided, the API key from the current environment or configuration will be used.
property Api.api_key
Returns W&B API key.
Returns:
str | None: The api_key property value.
property Api.client
Returns the client object.
Returns:
RetryingClient: The client property value.
property Api.default_entity
Returns the default W&B entity.
Returns:
str | None: The default_entity property value.
property Api.user_agent
Returns W&B public user agent.
Returns:
str: The user_agent property value.
property Api.viewer
Returns the viewer object.
Raises:
ValueError: If viewer data is not able to be fetched from W&B.requests.RequestException: If an error occurs while making the graphql request.
Returns:
public.User: The viewer property value.
method Api.artifact
artifact(name: str, type: Optional[str] = None)
Returns a single artifact.
Args:
name: The artifact’s name. The name of an artifact resembles a filepath that consists, at a minimum, the name of the project the artifact was logged to, the name of the artifact, and the artifact’s version or alias. Optionally append the entity that logged the artifact as a prefix followed by a forward slash. If no entity is specified in the name, the Run or API setting’s entity is used.type: The type of artifact to fetch.
Returns:
An Artifact object.
Raises:
ValueError: If the artifact name is not specified.ValueError: If the artifact type is specified but does not match the type of the fetched artifact.
Examples:
In the proceeding code snippets “entity”, “project”, “artifact”, “version”, and “alias” are placeholders for your W&B entity, name of the project the artifact is in, the name of the artifact, and artifact’s version, respectively.
import wandb
# Specify the project, artifact's name, and the artifact's alias
wandb.Api().artifact(name="project/artifact:alias")
# Specify the project, artifact's name, and a specific artifact version
wandb.Api().artifact(name="project/artifact:version")
# Specify the entity, project, artifact's name, and the artifact's alias
wandb.Api().artifact(name="entity/project/artifact:alias")
# Specify the entity, project, artifact's name, and a specific artifact version
wandb.Api().artifact(name="entity/project/artifact:version")
Note:
This method is intended for external use only. Do not call api.artifact() within the wandb repository code.
method Api.artifact_collection
artifact_collection(type_name: str, name: str) → public.ArtifactCollection
Returns a single artifact collection by type.
You can use the returned ArtifactCollection object to retrieve information about specific artifacts in that collection, and more.
Args:
type_name: The type of artifact collection to fetch.name: An artifact collection name. Optionally append the entity that logged the artifact as a prefix followed by a forward slash.
Returns:
An ArtifactCollection object.
Examples:
In the proceeding code snippet “type”, “entity”, “project”, and “artifact_name” are placeholders for the collection type, your W&B entity, name of the project the artifact is in, and the name of the artifact, respectively.
import wandb
collections = wandb.Api().artifact_collection(
type_name="type", name="entity/project/artifact_name"
)
# Get the first artifact in the collection
artifact_example = collections.artifacts()[0]
# Download the contents of the artifact to the specified root directory.
artifact_example.download()
method Api.artifact_collection_exists
artifact_collection_exists(name: str, type: str) → bool
Whether an artifact collection exists within a specified project and entity.
Args:
name: An artifact collection name. Optionally append the entity that logged the artifact as a prefix followed by a forward slash. If entity or project is not specified, infer the collection from the override params if they exist. Otherwise, entity is pulled from the user settings and project will default to “uncategorized”.type: The type of artifact collection.
Returns:
True if the artifact collection exists, False otherwise.
Examples:
In the proceeding code snippet “type”, and “collection_name” refer to the type of the artifact collection and the name of the collection, respectively.
import wandb
wandb.Api.artifact_collection_exists(type="type", name="collection_name")
method Api.artifact_collections
artifact_collections(
project_name: str,
type_name: str,
per_page: int = 50
) → public.ArtifactCollections
Returns a collection of matching artifact collections.
Args:
project_name: The name of the project to filter on.type_name: The name of the artifact type to filter on.per_page: Sets the page size for query pagination. None will use the default size. Usually there is no reason to change this.
Returns:
An iterable ArtifactCollections object.
method Api.artifact_exists
artifact_exists(name: str, type: Optional[str] = None) → bool
Whether an artifact version exists within the specified project and entity.
Args:
name: The name of artifact. Add the artifact’s entity and project as a prefix. Append the version or the alias of the artifact with a colon. If the entity or project is not specified, W&B uses override parameters if populated. Otherwise, the entity is pulled from the user settings and the project is set to “Uncategorized”.type: The type of artifact.
Returns:
True if the artifact version exists, False otherwise.
Examples:
In the proceeding code snippets “entity”, “project”, “artifact”, “version”, and “alias” are placeholders for your W&B entity, name of the project the artifact is in, the name of the artifact, and artifact’s version, respectively.
import wandb
wandb.Api().artifact_exists("entity/project/artifact:version")
wandb.Api().artifact_exists("entity/project/artifact:alias")
method Api.artifact_type
artifact_type(
type_name: str,
project: Optional[str] = None
) → public.ArtifactType
Returns the matching ArtifactType.
Args:
type_name: The name of the artifact type to retrieve.project: If given, a project name or path to filter on.
Returns:
An ArtifactType object.
method Api.artifact_types
artifact_types(project: Optional[str] = None) → public.ArtifactTypes
Returns a collection of matching artifact types.
Args:
project: The project name or path to filter on.
Returns:
An iterable ArtifactTypes object.
method Api.artifact_versions
artifact_versions(type_name, name, per_page=50)
Deprecated. Use Api.artifacts(type_name, name) method instead.
method Api.artifacts
artifacts(
type_name: str,
name: str,
per_page: int = 50,
tags: Optional[List[str]] = None
) → public.Artifacts
Return an Artifacts collection.
Args:
type_name: The type of artifacts to fetch. name: The artifact’s collection name. Optionally append the entity that logged the artifact as a prefix followed by a forward slash. per_page: Sets the page size for query pagination. If set to None, use the default size. Usually there is no reason to change this. tags: Only return artifacts with all of these tags.
Returns:
An iterable Artifacts object.
Examples:
In the proceeding code snippet, “type”, “entity”, “project”, and “artifact_name” are placeholders for the artifact type, W&B entity, name of the project the artifact was logged to, and the name of the artifact, respectively.
import wandb
wandb.Api().artifacts(type_name="type", name="entity/project/artifact_name")
method Api.automation
automation(name: str, entity: Optional[str] = None) → Automation
Returns the only Automation matching the parameters.
Args:
name: The name of the automation to fetch.entity: The entity to fetch the automation for.
Raises:
ValueError: If zero or multiple Automations match the search criteria.
Examples:
Get an existing automation named “my-automation”:
import wandb
api = wandb.Api()
automation = api.automation(name="my-automation")
Get an existing automation named “other-automation”, from the entity “my-team”:
automation = api.automation(name="other-automation", entity="my-team")
method Api.automations
automations(
entity: Optional[str] = None,
name: Optional[str] = None,
per_page: int = 50
) → Iterator[ForwardRef('Automation')]
Returns an iterator over all Automations that match the given parameters.
If no parameters are provided, the returned iterator will contain all Automations that the user has access to.
Args:
entity: The entity to fetch the automations for.name: The name of the automation to fetch.per_page: The number of automations to fetch per page. Defaults to 50. Usually there is no reason to change this.
Returns:
A list of automations.
Examples:
Fetch all existing automations for the entity “my-team”:
import wandb
api = wandb.Api()
automations = api.automations(entity="my-team")
method Api.create_automation
create_automation(
obj: 'NewAutomation',
fetch_existing: bool = False,
**kwargs: typing_extensions.Unpack[ForwardRef('WriteAutomationsKwargs')]
) → Automation
Create a new Automation.
Args:
obj: The automation to create. fetch_existing: If True, and a conflicting automation already exists, attempt to fetch the existing automation instead of raising an error. **kwargs: Any additional values to assign to the automation before creating it. If given, these will override any values that may already be set on the automation:
- name: The name of the automation.
- description: The description of the automation.
- enabled: Whether the automation is enabled.
- scope: The scope of the automation.
- event: The event that triggers the automation.
- action: The action that is triggered by the automation.
Returns:
The saved Automation.
Examples:
Create a new automation named “my-automation” that sends a Slack notification when a run within a specific project logs a metric exceeding a custom threshold:
import wandb
from wandb.automations import OnRunMetric, RunEvent, SendNotification
api = wandb.Api()
project = api.project("my-project", entity="my-team")
# Use the first Slack integration for the team
slack_hook = next(api.slack_integrations(entity="my-team"))
event = OnRunMetric(
scope=project,
filter=RunEvent.metric("custom-metric") > 10,
)
action = SendNotification.from_integration(slack_hook)
automation = api.create_automation(
event >> action,
name="my-automation",
description="Send a Slack message whenever 'custom-metric' exceeds 10.",
)
method Api.create_custom_chart
create_custom_chart(
entity: str,
name: str,
display_name: str,
spec_type: Literal['vega2'],
access: Literal['private', 'public'],
spec: Union[str, dict]
) → str
Create a custom chart preset and return its id.
Args:
entity: The entity (user or team) that owns the chartname: Unique identifier for the chart presetdisplay_name: Human-readable name shown in the UIspec_type: Type of specification. Must be “vega2” for Vega-Lite v2 specifications.access: Access level for the chart:
- “private”: Chart is only accessible to the entity that created it
- “public”: Chart is publicly accessiblespec: The Vega/Vega-Lite specification as a dictionary or JSON string
Returns:
The ID of the created chart preset in the format “entity/name”
Raises:
wandb.Error: If chart creation failsUnsupportedError: If the server doesn’t support custom charts
Example:
import wandb
api = wandb.Api()
# Define a simple bar chart specification
vega_spec = {
"$schema": "https://vega.github.io/schema/vega-lite/v6.json",
"mark": "bar",
"data": {"name": "wandb"},
"encoding": {
"x": {"field": "${field:x}", "type": "ordinal"},
"y": {"field": "${field:y}", "type": "quantitative"},
},
}
# Create the custom chart
chart_id = api.create_custom_chart(
entity="my-team",
name="my-bar-chart",
display_name="My Custom Bar Chart",
spec_type="vega2",
access="private",
spec=vega_spec,
)
# Use with wandb.plot_table()
chart = wandb.plot_table(
vega_spec_name=chart_id,
data_table=my_table,
fields={"x": "category", "y": "value"},
)
```
---
### <kbd>method</kbd> `Api.create_project`
```python
create_project(name: str, entity: str) → None
Create a new project.
Args:
name: The name of the new project.entity: The entity of the new project.
method Api.create_registry
create_registry(
name: str,
visibility: Literal['organization', 'restricted'],
organization: Optional[str] = None,
description: Optional[str] = None,
artifact_types: Optional[List[str]] = None
) → Registry
Create a new registry.
Args:
name: The name of the registry. Name must be unique within the organization.visibility: The visibility of the registry.organization: Anyone in the organization can view this registry. You can edit their roles later from the settings in the UI.restricted: Only invited members via the UI can access this registry. Public sharing is disabled.organization: The organization of the registry. If no organization is set in the settings, the organization will be fetched from the entity if the entity only belongs to one organization.description: The description of the registry.artifact_types: The accepted artifact types of the registry. A type is nomore than 128 characters and do not include characters /or ``:. If not specified, all types are accepted. Allowed types added to the registry cannot be removed later.
Returns:
A registry object.
Examples:
import wandb
api = wandb.Api()
registry = api.create_registry(
name="my-registry",
visibility="restricted",
organization="my-org",
description="This is a test registry",
artifact_types=["model"],
)
method Api.create_run
create_run(
run_id: Optional[str] = None,
project: Optional[str] = None,
entity: Optional[str] = None
) → public.Run
Create a new run.
Args:
run_id: The ID to assign to the run. If not specified, W&B creates a random ID.project: The project where to log the run to. If no project is specified, log the run to a project called “Uncategorized”.entity: The entity that owns the project. If no entity is specified, log the run to the default entity.
Returns:
The newly created Run.
method Api.create_run_queue
create_run_queue(
name: str,
type: 'public.RunQueueResourceType',
entity: Optional[str] = None,
prioritization_mode: Optional[ForwardRef('public.RunQueuePrioritizationMode')] = None,
config: Optional[dict] = None,
template_variables: Optional[dict] = None
) → public.RunQueue
Create a new run queue in W&B Launch.
Args:
name: Name of the queue to createtype: Type of resource to be used for the queue. One of “local-container”, “local-process”, “kubernetes”,“sagemaker”, or “gcp-vertex”.entity: Name of the entity to create the queue. If None, use the configured or default entity.prioritization_mode: Version of prioritization to use. Either “V0” or None.config: Default resource configuration to be used for the queue. Use handlebars (eg. {{var}}) to specify template variables.template_variables: A dictionary of template variable schemas to use with the config.
Returns:
The newly created RunQueue.
Raises:
ValueError if any of the parameters are invalid wandb.Error on wandb API errors
method Api.create_team
create_team(team: str, admin_username: Optional[str] = None) → public.Team
Create a new team.
Args:
team: The name of the teamadmin_username: Username of the admin user of the team. Defaults to the current user.
Returns:
A Team object.
method Api.create_user
create_user(email: str, admin: Optional[bool] = False)
Create a new user.
Args:
email: The email address of the user.admin: Set user as a global instance administrator.
Returns:
A User object.
method Api.delete_automation
delete_automation(obj: Union[ForwardRef('Automation'), str]) → Literal[True]
Delete an automation.
Args:
obj: The automation to delete, or its ID.
Returns:
True if the automation was deleted successfully.
method Api.flush
Flush the local cache.
The api object keeps a local cache of runs, so if the state of the run may change while executing your script you must clear the local cache with api.flush() to get the latest values associated with the run.
method Api.from_path
Return a run, sweep, project or report from a path.
Args:
path: The path to the project, run, sweep or report
Returns:
A Project, Run, Sweep, or BetaReport instance.
Raises:
wandb.Error if path is invalid or the object doesn’t exist.
Examples:
In the proceeding code snippets “project”, “team”, “run_id”, “sweep_id”, and “report_name” are placeholders for the project, team, run ID, sweep ID, and the name of a specific report, respectively.
import wandb
api = wandb.Api()
project = api.from_path("project")
team_project = api.from_path("team/project")
run = api.from_path("team/project/runs/run_id")
sweep = api.from_path("team/project/sweeps/sweep_id")
report = api.from_path("team/project/reports/report_name")
method Api.integrations
integrations(
entity: Optional[str] = None,
per_page: int = 50
) → Iterator[ForwardRef('Integration')]
Return an iterator of all integrations for an entity.
Args:
entity: The entity (e.g. team name) for which to fetch integrations. If not provided, the user’s default entity will be used.per_page: Number of integrations to fetch per page. Defaults to 50. Usually there is no reason to change this.
Yields:
Iterator[SlackIntegration | WebhookIntegration]: An iterator of any supported integrations.
method Api.job
job(name: Optional[str], path: Optional[str] = None) → public.Job
Return a Job object.
Args:
name: The name of the job.path: The root path to download the job artifact.
Returns:
A Job object.
method Api.list_jobs
list_jobs(entity: str, project: str) → List[Dict[str, Any]]
Return a list of jobs, if any, for the given entity and project.
Args:
entity: The entity for the listed jobs.project: The project for the listed jobs.
Returns:
A list of matching jobs.
method Api.project
project(name: str, entity: Optional[str] = None) → public.Project
Return the Project with the given name (and entity, if given).
Args:
name: The project name.entity: Name of the entity requested. If None, will fall back to the default entity passed to Api. If no default entity, will raise a ValueError.
Returns:
A Project object.
method Api.projects
projects(entity: Optional[str] = None, per_page: int = 200) → public.Projects
Get projects for a given entity.
Args:
entity: Name of the entity requested. If None, will fall back to the default entity passed to Api. If no default entity, will raise a ValueError.per_page: Sets the page size for query pagination. If set to None, use the default size. Usually there is no reason to change this.
Returns:
A Projects object which is an iterable collection of Projectobjects.
method Api.queued_run
queued_run(
entity: str,
project: str,
queue_name: str,
run_queue_item_id: str,
project_queue=None,
priority=None
)
Return a single queued run based on the path.
Parses paths of the form entity/project/queue_id/run_queue_item_id.
method Api.registries
registries(
organization: Optional[str] = None,
filter: Optional[Dict[str, Any]] = None
) → Registries
Returns a lazy iterator of Registry objects.
Use the iterator to search and filter registries, collections, or artifact versions across your organization’s registry.
Args:
organization: (str, optional) The organization of the registry to fetch. If not specified, use the organization specified in the user’s settings.filter: (dict, optional) MongoDB-style filter to apply to each object in the lazy registry iterator. Fields available to filter for registries are name, description, created_at, updated_at. Fields available to filter for collections are name, tag, description, created_at, updated_at Fields available to filter for versions are tag, alias, created_at, updated_at, metadata
Returns:
A lazy iterator of Registry objects.
Examples:
Find all registries with the names that contain “model”
import wandb
api = wandb.Api() # specify an org if your entity belongs to multiple orgs
api.registries(filter={"name": {"$regex": "model"}})
Find all collections in the registries with the name “my_collection” and the tag “my_tag”
api.registries().collections(filter={"name": "my_collection", "tag": "my_tag"})
Find all artifact versions in the registries with a collection name that contains “my_collection” and a version that has the alias “best”
api.registries().collections(
filter={"name": {"$regex": "my_collection"}}
).versions(filter={"alias": "best"})
Find all artifact versions in the registries that contain “model” and have the tag “prod” or alias “best”
api.registries(filter={"name": {"$regex": "model"}}).versions(
filter={"$or": [{"tag": "prod"}, {"alias": "best"}]}
)
method Api.registry
registry(name: str, organization: Optional[str] = None) → Registry
Return a registry given a registry name.
Args:
name: The name of the registry. This is without the wandb-registry- prefix.organization: The organization of the registry. If no organization is set in the settings, the organization will be fetched from the entity if the entity only belongs to one organization.
Returns:
A registry object.
Examples:
Fetch and update a registry
import wandb
api = wandb.Api()
registry = api.registry(name="my-registry", organization="my-org")
registry.description = "This is an updated description"
registry.save()
method Api.reports
reports(
path: str = '',
name: Optional[str] = None,
per_page: int = 50
) → public.Reports
Get reports for a given project path.
Note: wandb.Api.reports() API is in beta and will likely change in future releases.
Args:
path: The path to the project the report resides in. Specify the entity that created the project as a prefix followed by a forward slash.name: Name of the report requested.per_page: Sets the page size for query pagination. If set to None, use the default size. Usually there is no reason to change this.
Returns:
A Reports object which is an iterable collection of BetaReport objects.
Examples:
import wandb
wandb.Api.reports("entity/project")
method Api.run
Return a single run by parsing path in the form entity/project/run_id.
Args:
path: Path to run in the form entity/project/run_id. If api.entity is set, this can be in the form project/run_id and if api.project is set this can just be the run_id.
Returns:
A Run object.
method Api.run_queue
run_queue(entity: str, name: str)
Return the named RunQueue for entity.
See Api.create_run_queue for more information on how to create a run queue.
method Api.runs
runs(
path: Optional[str] = None,
filters: Optional[Dict[str, Any]] = None,
order: str = '+created_at',
per_page: int = 50,
include_sweeps: bool = True
)
Returns a Runs object, which lazily iterates over Run objects.
Fields you can filter by include:
createdAt: The timestamp when the run was created. (in ISO 8601 format, e.g. “2023-01-01T12:00:00Z”)displayName: The human-readable display name of the run. (e.g. “eager-fox-1”)duration: The total runtime of the run in seconds.group: The group name used to organize related runs together.host: The hostname where the run was executed.jobType: The type of job or purpose of the run.name: The unique identifier of the run. (e.g. “a1b2cdef”)state: The current state of the run.tags: The tags associated with the run.username: The username of the user who initiated the run
Additionally, you can filter by items in the run config or summary metrics. Such as config.experiment_name, summary_metrics.loss, etc.
For more complex filtering, you can use MongoDB query operators. For details, see: https://docs.mongodb.com/manual/reference/operator/query The following operations are supported:
$and$or$nor$eq$ne$gt$gte$lt$lte$in$nin$exists$regex
Args:
path: (str) path to project, should be in the form: “entity/project”filters: (dict) queries for specific runs using the MongoDB query language. You can filter by run properties such as config.key, summary_metrics.key, state, entity, createdAt, etc.For example: {"config.experiment_name": "foo"} would find runs with a config entry of experiment name set to “foo”order: (str) Order can be created_at, heartbeat_at, config.*.value, or summary_metrics.*. If you prepend order with a + order is ascending (default). If you prepend order with a - order is descending. The default order is run.created_at from oldest to newest.per_page: (int) Sets the page size for query pagination.include_sweeps: (bool) Whether to include the sweep runs in the results.
Returns:
A Runs object, which is an iterable collection of Run objects.
Examples:
# Find runs in project where config.experiment_name has been set to "foo"
api.runs(path="my_entity/project", filters={"config.experiment_name": "foo"})
# Find runs in project where config.experiment_name has been set to "foo" or "bar"
api.runs(
path="my_entity/project",
filters={
"$or": [
{"config.experiment_name": "foo"},
{"config.experiment_name": "bar"},
]
},
)
# Find runs in project where config.experiment_name matches a regex
# (anchors are not supported)
api.runs(
path="my_entity/project",
filters={"config.experiment_name": {"$regex": "b.*"}},
)
# Find runs in project where the run name matches a regex
# (anchors are not supported)
api.runs(
path="my_entity/project", filters={"display_name": {"$regex": "^foo.*"}}
)
# Find runs in project sorted by ascending loss
api.runs(path="my_entity/project", order="+summary_metrics.loss")
method Api.slack_integrations
slack_integrations(
entity: Optional[str] = None,
per_page: int = 50
) → Iterator[ForwardRef('SlackIntegration')]
Returns an iterator of Slack integrations for an entity.
Args:
entity: The entity (e.g. team name) for which to fetch integrations. If not provided, the user’s default entity will be used.per_page: Number of integrations to fetch per page. Defaults to 50. Usually there is no reason to change this.
Yields:
Iterator[SlackIntegration]: An iterator of Slack integrations.
Examples:
Get all registered Slack integrations for the team “my-team”:
import wandb
api = wandb.Api()
slack_integrations = api.slack_integrations(entity="my-team")
Find only Slack integrations that post to channel names starting with “team-alerts-”:
slack_integrations = api.slack_integrations(entity="my-team")
team_alert_integrations = [
ig
for ig in slack_integrations
if ig.channel_name.startswith("team-alerts-")
]
method Api.sweep
Return a sweep by parsing path in the form entity/project/sweep_id.
Args:
path: Path to sweep in the form entity/project/sweep_id. If api.entity is set, this can be in the form project/sweep_id and if api.project is set this can just be the sweep_id.
Returns:
A Sweep object.
method Api.sync_tensorboard
sync_tensorboard(root_dir, run_id=None, project=None, entity=None)
Sync a local directory containing tfevent files to wandb.
method Api.team
team(team: str) → public.Team
Return the matching Team with the given name.
Args:
team: The name of the team.
Returns:
A Team object.
method Api.update_automation
update_automation(
obj: 'Automation',
create_missing: bool = False,
**kwargs: typing_extensions.Unpack[ForwardRef('WriteAutomationsKwargs')]
) → Automation
Update an existing automation.
Args:
obj: The automation to update. Must be an existing automation. create_missing (bool): If True, and the automation does not exist, create it. **kwargs: Any additional values to assign to the automation before updating it. If given, these will override any values that may already be set on the automation:
- name: The name of the automation.
- description: The description of the automation.
- enabled: Whether the automation is enabled.
- scope: The scope of the automation.
- event: The event that triggers the automation.
- action: The action that is triggered by the automation.
Returns:
The updated automation.
Examples:
Disable and edit the description of an existing automation (“my-automation”):
import wandb
api = wandb.Api()
automation = api.automation(name="my-automation")
automation.enabled = False
automation.description = "Kept for reference, but no longer used."
updated_automation = api.update_automation(automation)
OR
import wandb
api = wandb.Api()
automation = api.automation(name="my-automation")
updated_automation = api.update_automation(
automation,
enabled=False,
description="Kept for reference, but no longer used.",
)
method Api.upsert_run_queue
upsert_run_queue(
name: str,
resource_config: dict,
resource_type: 'public.RunQueueResourceType',
entity: Optional[str] = None,
template_variables: Optional[dict] = None,
external_links: Optional[dict] = None,
prioritization_mode: Optional[ForwardRef('public.RunQueuePrioritizationMode')] = None
)
Upsert a run queue in W&B Launch.
Args:
name: Name of the queue to createentity: Optional name of the entity to create the queue. If None, use the configured or default entity.resource_config: Optional default resource configuration to be used for the queue. Use handlebars (eg. {{var}}) to specify template variables.resource_type: Type of resource to be used for the queue. One of “local-container”, “local-process”, “kubernetes”, “sagemaker”, or “gcp-vertex”.template_variables: A dictionary of template variable schemas to be used with the config.external_links: Optional dictionary of external links to be used with the queue.prioritization_mode: Optional version of prioritization to use. Either “V0” or None
Returns:
The upserted RunQueue.
Raises:
ValueError if any of the parameters are invalid wandb.Error on wandb API errors
method Api.user
user(username_or_email: str) → Optional[ForwardRef('public.User')]
Return a user from a username or email address.
This function only works for local administrators. Use api.viewer to get your own user object.
Args:
username_or_email: The username or email address of the user.
Returns:
A User object or None if a user is not found.
method Api.users
users(username_or_email: str) → List[ForwardRef('public.User')]
Return all users from a partial username or email address query.
This function only works for local administrators. Use api.viewer to get your own user object.
Args:
username_or_email: The prefix or suffix of the user you want to find.
Returns:
An array of User objects.
method Api.webhook_integrations
webhook_integrations(
entity: Optional[str] = None,
per_page: int = 50
) → Iterator[ForwardRef('WebhookIntegration')]
Returns an iterator of webhook integrations for an entity.
Args:
entity: The entity (e.g. team name) for which to fetch integrations. If not provided, the user’s default entity will be used.per_page: Number of integrations to fetch per page. Defaults to 50. Usually there is no reason to change this.
Yields:
Iterator[WebhookIntegration]: An iterator of webhook integrations.
Examples:
Get all registered webhook integrations for the team “my-team”:
import wandb
api = wandb.Api()
webhook_integrations = api.webhook_integrations(entity="my-team")
Find only webhook integrations that post requests to “https://my-fake-url.com”:
webhook_integrations = api.webhook_integrations(entity="my-team")
my_webhooks = [
ig
for ig in webhook_integrations
if ig.url_endpoint.startswith("https://my-fake-url.com")
]
17 - Run
Training and fine-tuning models is done elsewhere in the W&B Python SDK. Use the Public API for querying and managing data after it has been logged to W&B.
class Run
A single run associated with an entity and project.
method Run.__init__
__init__(
client: 'RetryingClient',
entity: 'str',
project: 'str',
run_id: 'str',
attrs: 'Mapping | None' = None,
include_sweeps: '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 runurl (str): the url of this runid (str): unique identifier for the run (defaults to eight characters)name (str): the name of the runstate (str): one of: running, finished, crashed, killed, preempting, preemptedconfig (dict): a dict of hyperparameters associated with the runcreated_at (str): ISO timestamp when the run was startedsystem_metrics (dict): the latest system metrics recorded for the runsummary (dict): A mutable dict-like property that holds the current summary. Calling update will persist any changes.project (str): the project associated with the runentity (str): the name of the entity associated with the runproject_internal_id (int): the internal id of the projectuser (str): the name of the user who created the runpath (str): Unique identifier [entity]/[project]/[run_id]notes (str): Notes about the runread_only (boolean): Whether the run is editablehistory_keys (str): Keys of the history metrics that have been loggedwith 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.
property Run.entity
The entity associated with the run.
property Run.id
The unique identifier for the run.
property Run.lastHistoryStep
Returns the last step logged in the run’s history.
Metadata about the run from wandb-metadata.json.
Metadata includes the run’s description, tags, start time, memory usage and more.
property Run.name
The name of the run.
property Run.path
The path of the run. The path is a list containing the entity, project, and run_id.
property Run.state
The state of the run. Can be one of: Finished, Failed, Crashed, or Running.
property Run.storage_id
The unique storage identifier for the run.
property Run.summary
A mutable dict-like property that holds summary values associated with the run.
property 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.
property Run.username
This API is deprecated. Use entity instead.
classmethod Run.create
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.
method Run.delete
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.
method Run.file
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.
method Run.files
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 filespattern (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.
method Run.history
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 returnpandas : (bool, optional) Return a pandas dataframekeys : (list, optional) Only return metrics for specific keysx_axis : (str, optional) Use this metric as the xAxis defaults to _stepstream : (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.
method Run.load
method Run.log_artifact
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.
method Run.logged_artifacts
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:
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
Persist changes to the run object to the W&B backend.
method Run.scan_history
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
run = api.run("entity/project-name/run-id")
history = run.scan_history(keys=["Loss"])
losses = [row["Loss"] for row in history]
method Run.to_html
to_html(height=420, hidden=False)
Generate HTML containing an iframe displaying this run.
method Run.update
Persist changes to the run object to the wandb backend.
method Run.upload_file
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.
method Run.use_artifact
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.
method Run.used_artifacts
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:
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
Check the state of the run until it is finished.