Import & Export API

• 1: Api
• 2: ArtifactCollection
• 3: ArtifactCollections
• 4: ArtifactFiles
• 5: Artifacts
• 6: ArtifactType
• 7: ArtifactTypes
• 8: Automations
• 9: BetaReport
• 10: File
• 11: Files
• 12: Member
• 13: Project
• 14: Projects
• 15: Registry
• 16: Reports
• 17: Run
• 18: RunArtifacts
• 19: Runs
• 20: Sweep
• 21: Sweeps
• 22: Team
• 23: User

1 - Api

Used for querying the W&B server.

Examples:

import wandb

wandb.Api()

Methods

artifact

View source

artifact(
    name: str,
    type: (str | None) = None
)

Returns a single 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.

artifact_collection

View source

artifact_collection(
    type_name: str,
    name: str
) -> 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.

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

artifact_collection_exists

View source

artifact_collection_exists(
    name: str,
    type: str
) -> bool

Whether an artifact collection exists within a specified project and entity.

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

artifact_collections

View source

artifact_collections(
    project_name: str,
    type_name: str,
    per_page: int = 50
) -> ArtifactCollections

Returns a collection of matching artifact collections.

artifact_exists

View source

artifact_exists(
    name: str,
    type: (str | None) = None
) -> bool

Whether an artifact version exists within the specified project and entity.

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

artifact_type

View source

artifact_type(
    type_name: str,
    project: (str | None) = None
) -> ArtifactType

Returns the matching ArtifactType.

artifact_types

View source

artifact_types(
    project: (str | None) = None
) -> ArtifactTypes

Returns a collection of matching artifact types.

artifact_versions

View source

artifact_versions(
    type_name, name, per_page=50
)

Deprecated. Use Api.artifacts(type_name, name) method instead.

artifacts

View source

artifacts(
    type_name: str,
    name: str,
    per_page: int = 50,
    tags: (list[str] | None) = None
) -> Artifacts

Return an Artifacts collection.

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.

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

automation

View source

automation(
    name: str,
    *,
    entity: (str | None) = None
) -> Automation

Returns the only Automation matching the parameters.

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

automations

View source

automations(
    entity: (str | None) = None,
    *,
    name: (str | None) = None,
    per_page: int = 50
) -> Iterator[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.

Examples:

Fetch all existing automations for the entity “my-team”:

import wandb

api = wandb.Api()
automations = api.automations(entity="my-team")

create_automation

View source

create_automation(
    obj: NewAutomation,
    *,
    fetch_existing: bool = (False),
    **kwargs
) -> Automation

Create a new 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.",
)

create_custom_chart

View source

create_custom_chart(
    entity: str,
    name: str,
    display_name: str,
    spec_type: Literal['vega2'],
    access: Literal['private', 'public'],
    spec: (str | dict)
) -> str

Create a custom chart preset and return its id.

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"},
)

create_project

View source

create_project(
    name: str,
    entity: str
) -> None

Create a new project.

create_registry

View source

create_registry(
    name: str,
    visibility: Literal['organization', 'restricted'],
    organization: (str | None) = None,
    description: (str | None) = None,
    artifact_types: (list[str] | None) = None
) -> Registry

Create a new registry.

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"],
)

create_run

View source

create_run(
    *,
    run_id: (str | None) = None,
    project: (str | None) = None,
    entity: (str | None) = None
) -> public.Run

Create a new run.

create_run_queue

View source

create_run_queue(
    name: str,
    type: public.RunQueueResourceType,
    entity: (str | None) = None,
    prioritization_mode: (public.RunQueuePrioritizationMode | None) = None,
    config: (dict | None) = None,
    template_variables: (dict | None) = None
) -> public.RunQueue

Create a new run queue in W&B Launch.

create_team

View source

create_team(
    team: str,
    admin_username: (str | None) = None
) -> Team

Create a new team.

create_user

View source

create_user(
    email: str,
    admin: (bool | None) = (False)
) -> User

Create a new user.

delete_automation

View source

delete_automation(
    obj: (Automation | str)
) -> Literal[True]

Delete an automation.

flush

View source

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.

from_path

View source

from_path(
    path: str
)

Return a run, sweep, project or report from a path.

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

integrations

View source

integrations(
    entity: (str | None) = None,
    *,
    per_page: int = 50
) -> Iterator[Integration]

Return an iterator of all integrations for an entity.

job

View source

job(
    name: (str | None),
    path: (str | None) = None
) -> public.Job

Return a Job object.

list_jobs

View source

list_jobs(
    entity: str,
    project: str
) -> list[dict[str, Any]]

Return a list of jobs, if any, for the given entity and project.

project

View source

project(
    name: str,
    entity: (str | None) = None
) -> public.Project

Return the Project with the given name (and entity, if given).

projects

View source

projects(
    entity: (str | None) = None,
    per_page: int = 200
) -> public.Projects

Get projects for a given entity.

queued_run

View source

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.

registries

View source

registries(
    organization: (str | None) = None,
    filter: (dict[str, Any] | None) = 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.

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"}]}
)

registry

View source

registry(
    name: str,
    organization: (str | None) = None
) -> Registry

Return a registry given a registry name.

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

reports

View source

reports(
    path: str = "",
    name: (str | None) = 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.

Examples:

import wandb

wandb.Api.reports("entity/project")

run

View source

run(
    path=""
)

Return a single run by parsing path in the form entity/project/run_id.

run_queue

View source

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.

runs

View source

runs(
    path: (str | None) = None,
    filters: (dict[str, Any] | None) = None,
    order: str = "+created_at",
    per_page: int = 50,
    include_sweeps: bool = (True),
    lazy: 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

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

slack_integrations

View source

slack_integrations(
    *,
    entity: (str | None) = None,
    per_page: int = 50
) -> Iterator[SlackIntegration]

Returns an iterator of Slack integrations for an entity.

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-")
]

sweep

View source

sweep(
    path=""
)

Return a sweep by parsing path in the form entity/project/sweep_id.

sync_tensorboard

View source

sync_tensorboard(
    root_dir, run_id=None, project=None, entity=None
)

Sync a local directory containing tfevent files to wandb.

team

View source

team(
    team: str
) -> Team

Return the matching Team with the given name.

update_automation

View source

update_automation(
    obj: Automation,
    *,
    create_missing: bool = (False),
    **kwargs
) -> Automation

Update an existing 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.",
)

upsert_run_queue

View source

upsert_run_queue(
    name: str,
    resource_config: dict,
    resource_type: public.RunQueueResourceType,
    entity: (str | None) = None,
    template_variables: (dict | None) = None,
    external_links: (dict | None) = None,
    prioritization_mode: (public.RunQueuePrioritizationMode | None) = None
)

Upsert a run queue in W&B Launch.

user

View source

user(
    username_or_email: str
) -> (User | None)

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.

users

View source

users(
    username_or_email: str
) -> list[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.

webhook_integrations

View source

webhook_integrations(
    entity: (str | None) = None,
    *,
    per_page: int = 50
) -> Iterator[WebhookIntegration]

Returns an iterator of webhook integrations for an entity.

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")
]

2 - ArtifactCollection

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 ArtifactCollection

An artifact collection that represents a group of related artifacts.

Args:

• client: The client instance to use for querying W&B.
• entity: The entity (user or team) that owns the project.
• project: The name of the project to query for artifact collections.
• name: The name of the artifact collection.
• type: The type of the artifact collection (e.g., “dataset”, “model”).
• organization: Optional organization name if applicable.
• attrs: Optional mapping of attributes to initialize the artifact collection. If not provided, the object will load its attributes from W&B upon initialization.

property ArtifactCollection.aliases

Artifact Collection Aliases.

Returns:

• list[str]: The aliases property value.

property ArtifactCollection.created_at

The creation date of the artifact collection.

Returns:

• str: The created_at property value.

property ArtifactCollection.description

A description of the artifact collection.

Returns:

• str: The description property value.

property ArtifactCollection.id

The unique identifier of the artifact collection.

Returns:

• str: The id property value.

property ArtifactCollection.name

The name of the artifact collection.

Returns:

• str: The name property value.

property ArtifactCollection.tags

The tags associated with the artifact collection.

Returns:

• list[str]: The tags property value.

property ArtifactCollection.type

Returns the type of the artifact collection.

method ArtifactCollection.artifacts

artifacts(per_page: 'int' = 50) → Artifacts

Get all artifacts in the collection.

method ArtifactCollection.change_type

change_type(new_type: 'str') → None

Deprecated, change type directly with save instead.

method ArtifactCollection.delete

delete() → None

Delete the entire artifact collection.

method ArtifactCollection.is_sequence

is_sequence() → bool

Return whether the artifact collection is a sequence.

method ArtifactCollection.save

save() → None

Persist any changes made to the artifact collection.

3 - ArtifactCollections

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 ArtifactCollections

Artifact collections of a specific type in a project.

Args:

• client: The client instance to use for querying W&B.
• entity: The entity (user or team) that owns the project.
• project: The name of the project to query for artifact collections.
• type_name: The name of the artifact type for which to fetch collections.
• per_page: The number of artifact collections to fetch per page. Default is 50.

property ArtifactCollections.length

4 - ArtifactFiles

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 ArtifactFiles

A paginator for files in an artifact.

property ArtifactFiles.length

property ArtifactFiles.path

Returns the path of the artifact.

Returns:

• list[str]: The path property value.

5 - Artifacts

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 Artifacts

An iterable collection of artifact versions associated with a project.

Optionally pass in filters to narrow down the results based on specific criteria.

Args:

• client: The client instance to use for querying W&B.
• entity: The entity (user or team) that owns the project.
• project: The name of the project to query for artifacts.
• collection_name: The name of the artifact collection to query.
• type: The type of the artifacts to query. Common examples include “dataset” or “model”.
• filters: Optional mapping of filters to apply to the query.
• order: Optional string to specify the order of the results.
• per_page: The number of artifact versions to fetch per page. Default is 50.
• tags: Optional string or list of strings to filter artifacts by tags.

property Artifacts.length

6 - ArtifactType

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 ArtifactType

An artifact object that satisfies query based on the specified type.

Args:

• client: The client instance to use for querying W&B.
• entity: The entity (user or team) that owns the project.
• project: The name of the project to query for artifact types.
• type_name: The name of the artifact type.
• attrs: Optional mapping of attributes to initialize the artifact type. If not provided, the object will load its attributes from W&B upon initialization.

property ArtifactType.id

The unique identifier of the artifact type.

Returns:

• str: The id property value.

property ArtifactType.name

The name of the artifact type.

Returns:

• str: The name property value.

method ArtifactType.collection

collection(name: 'str') → ArtifactCollection

Get a specific artifact collection by name.

Args:

• name (str): The name of the artifact collection to retrieve.

method ArtifactType.collections

collections(per_page: 'int' = 50) → ArtifactCollections

Get all artifact collections associated with this artifact type.

Args:

• per_page (int): The number of artifact collections to fetch per page. Default is 50.

7 - ArtifactTypes

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 ArtifactTypes

An lazy iterator of ArtifactType objects for a specific project.

8 - Automations

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 Automations

An lazy iterator of Automation objects.

9 - BetaReport

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 BetaReport

BetaReport is a class associated with reports created in W&B.

Provides access to report attributes (name, description, user, spec, timestamps) and methods for retrieving associated runs, sections, and for rendering the report as HTML.

Attributes:

• id (string): Unique identifier of the report.
• display_name (string): Human-readable display name of the report.
• name (string): The name of the report. Use display_name for a more user-friendly name.
• description (string): Description of the report.
• user (User): Dictionary containing user info (username, email) who created the report.
• spec (dict): The spec of the report.
• url (string): The URL of the report.
• updated_at (string): Timestamp of last update.
• created_at (string): Timestamp when the report was created.

method BetaReport.__init__

__init__(client, attrs, entity=None, project=None)

property BetaReport.created_at

property BetaReport.description

property BetaReport.display_name

property BetaReport.id

property BetaReport.name

property BetaReport.sections

Get the panel sections (groups) from the report.

property BetaReport.spec

property BetaReport.updated_at

property BetaReport.url

property BetaReport.user

method BetaReport.runs

runs(section, per_page=50, only_selected=True)

Get runs associated with a section of the report.

method BetaReport.to_html

to_html(height=1024, hidden=False)

Generate HTML containing an iframe displaying this report.

10 - File

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 File

File saved to W&B.

Represents a single file stored in W&B. Includes access to file metadata. Files are associated with a specific run and can include text files, model weights, datasets, visualizations, and other artifacts. You can download the file, delete the file, and access file properties.

Specify one or more attributes in a dictionary to fine a specific file logged to a specific run. You can search using the following keys:

• id (str): The ID of the run that contains the file
• name (str): Name of the file
• url (str): path to file
• direct_url (str): path to file in the bucket
• sizeBytes (int): size of file in bytes
• md5 (str): md5 of file
• mimetype (str): mimetype of file
• updated_at (str): timestamp of last update
• path_uri (str): path to file in the bucket, currently only available for S3 objects and reference files

Args:

• client: The run object that contains the file
• attrs (dict): A dictionary of attributes that define the file
• run: The run object that contains the file

property File.path_uri

Returns the URI path to the file in the storage bucket.

Returns:

• str: The S3 URI (e.g., ‘s3://bucket/path/to/file’) if the file is stored in S3, the direct URL if it’s a reference file, or an empty string if unavailable.

Returns:

• str: The path_uri property value.

property File.size

Returns the size of the file in bytes.

method File.delete

delete()

Delete the file from the W&B server.

method File.download

download(
    root: 'str' = '.',
    replace: 'bool' = False,
    exist_ok: 'bool' = False,
    api: 'Api | None' = None
) → io.TextIOWrapper

Downloads a file previously saved by a run from the wandb server.

Args:

• root: Local directory to save the file. Defaults to the current working directory (".").
• replace: If True, download will overwrite a local file if it exists. Defaults to False.
• exist_ok: If True, will not raise ValueError if file already exists and will not re-download unless replace=True. Defaults to False.
• api: If specified, the Api instance used to download the file.

Raises: ValueError if file already exists, replace=False and exist_ok=False.

11 - Files

A lazy iterator over a collection of File objects.

Access and manage files uploaded to W&B during a run. Handles pagination automatically when iterating through large collections of files.

Example:

from wandb.apis.public.files import Files
from wandb.apis.public.api import Api

# Example run object
run = Api().run("entity/project/run-id")

# Create a Files object to iterate over files in the run
files = Files(api.client, run)

# Iterate over files
for file in files:
    print(file.name)
    print(file.url)
    print(file.size)

    # Download the file
    file.download(root="download_directory", replace=True)

Methods

convert_objects

View source

convert_objects()

Converts GraphQL edges to File objects.

next

View source

next() -> T

Return the next item from the iterator. When exhausted, raise StopIteration

update_variables

View source

update_variables()

Updates the GraphQL query variables for pagination.

__getitem__

View source

__getitem__(
    index: (int | slice)
) -> (T | list[T])

__iter__

View source

__iter__() -> Iterator[T]

__len__

View source

__len__() -> int

12 - Member

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 Member

A member of a team.

method Member.__init__

__init__(client, team, attrs)

Args:

• client (wandb.apis.internal.Api): The client instance to use
• team (str): The name of the team this member belongs to
• attrs (dict): The member attributes

method Member.delete

delete()

Remove a member from a team.

Returns: Boolean indicating success

13 - Project

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 Project

A project is a namespace for runs.

method Project.__init__

__init__(
    client: wandb.apis.public.api.RetryingClient,
    entity: str,
    project: str,
    attrs: dict
) → Project

Args:

• client: W&B API client instance.
• name (str): The name of the project.
• entity (str): The entity name that owns the project.

A single project associated with an entity.

Args:

• client: The API client used to query W&B.
• entity: The entity which owns the project.
• project: The name of the project to query.
• attrs: The attributes of the project.

property Project.id

property Project.path

Returns the path of the project. The path is a list containing the entity and project name.

property Project.url

Returns the URL of the project.

method Project.artifacts_types

artifacts_types(per_page=50)

Returns all artifact types associated with this project.

method Project.sweeps

sweeps(per_page=50)

Return a paginated collection of sweeps in this project.

Args:

• per_page: The number of sweeps to fetch per request to the API.

Returns: A Sweeps object, which is an iterable collection of Sweep objects.

14 - Projects

An lazy iterator of Project objects.

An iterable interface to access projects created and saved by the entity.

Example:

from wandb.apis.public.api import Api

# Find projects that belong to this entity
projects = Api().projects(entity="entity")

# Iterate over files
for project in projects:
    print(f"Project: {project.name}")
    print(f"- URL: {project.url}")
    print(f"- Created at: {project.created_at}")
    print(f"- Is benchmark: {project.is_benchmark}")

Methods

convert_objects

View source

convert_objects()

Converts GraphQL edges to File objects.

next

View source

next() -> T

Return the next item from the iterator. When exhausted, raise StopIteration

update_variables

View source

update_variables() -> None

Update the query variables for the next page fetch.

__getitem__

View source

__getitem__(
    index: (int | slice)
) -> (T | list[T])

__iter__

View source

__iter__() -> Iterator[T]

15 - Registry

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 Registry

A single registry in the Registry.

method Registry.__init__

__init__(
    client: 'Client',
    organization: str,
    entity: str,
    name: str,
    attrs: Optional[Dict[str, Any]] = None
)

property Registry.allow_all_artifact_types

Returns whether all artifact types are allowed in the registry.

If True then artifacts of any type can be added to this registry. If False then artifacts are restricted to the types in artifact_types for this registry.

property Registry.artifact_types

Returns the artifact types allowed in the registry.

If allow_all_artifact_types is True then artifact_types reflects the types previously saved or currently used in the registry. If allow_all_artifact_types is False then artifacts are restricted to the types in artifact_types.

Note:

Previously saved artifact types cannot be removed.

Example:

import wandb

registry = wandb.Api().create_registry()
registry.artifact_types.append("model")
registry.save()  # once saved, the artifact type `model` cannot be removed
registry.artifact_types.append("accidentally_added")
registry.artifact_types.remove(
    "accidentally_added"
)  # Types can only be removed if it has not been saved yet

Returns:

• AddOnlyArtifactTypesList: The artifact_types property value.

property Registry.created_at

Timestamp of when the registry was created.

Returns:

• str: The created_at property value.

property Registry.description

Description of the registry.

Returns:

• str: The description property value.

property Registry.entity

Organization entity of the registry.

Returns:

• str: The entity property value.

property Registry.full_name

Full name of the registry including the wandb-registry- prefix.

Returns:

• str: The full_name property value.

property Registry.name

Name of the registry without the wandb-registry- prefix.

Returns:

• str: The name property value.

property Registry.organization

Organization name of the registry.

Returns:

• str: The organization property value.

property Registry.path

property Registry.updated_at

Timestamp of when the registry was last updated.

Returns:

• str: The updated_at property value.

property Registry.visibility

Visibility of the registry.

Returns:

• Literal["organization", "restricted"]: The visibility level. - “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.

Returns:

• Literal: The visibility property value.

method Registry.collections

collections(filter: Optional[Dict[str, Any]] = None) → Collections

Returns the collections belonging to the registry.

classmethod Registry.create

create(
    client: 'Client',
    organization: str,
    name: str,
    visibility: Literal['organization', 'restricted'],
    description: Optional[str] = None,
    artifact_types: Optional[List[str]] = None
)

Create a new registry.

The registry name must be unique within the organization. This function should be called using api.create_registry()

Args:

• client: The GraphQL client.
• organization: The name of the organization.
• name: The name of the registry (without the wandb-registry- prefix).
• visibility: The visibility level (‘organization’ or ‘restricted’).
• description: An optional description for the registry.
• artifact_types: An optional list of allowed artifact types.

Returns:

• Registry: The newly created Registry object.

Raises:

• ValueError: If a registry with the same name already exists in the organization or if the creation fails.

method Registry.delete

delete() → None

Delete the registry. This is irreversible.

method Registry.load

load() → None

Load the registry attributes from the backend to reflect the latest saved state.

method Registry.save

save() → None

Save registry attributes to the backend.

method Registry.versions

versions(filter: Optional[Dict[str, Any]] = None) → Versions

Returns the versions belonging to the registry.

16 - Reports

Reports is a lazy iterator of BetaReport objects.

Methods

convert_objects

View source

convert_objects()

Converts GraphQL edges to File objects.

next

View source

next() -> T

Return the next item from the iterator. When exhausted, raise StopIteration

update_variables

View source

update_variables()

Updates the GraphQL query variables for pagination.

__getitem__

View source

__getitem__(
    index: (int | slice)
) -> (T | list[T])

__iter__

View source

__iter__() -> Iterator[T]

__len__

View source

__len__() -> int

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

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.

property Run.metadata

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

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.

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

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

method Run.load

load(force=False)

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

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

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

wait_until_finished()

Check the state of the run until it is finished.

18 - RunArtifacts

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 RunArtifacts

An iterable collection of artifacts associated with a specific run.

property RunArtifacts.length

19 - Runs

A lazy iterator of Run objects associated with a project and optional filter.

Runs are retrieved in pages from the W&B server as needed.

This is generally used indirectly using the Api.runs namespace.

Examples:

from wandb.apis.public.runs import Runs
from wandb.apis.public import Api

# Get all runs from a project that satisfy the filters
filters = {"state": "finished", "config.optimizer": "adam"}

runs = Api().runs(
    client=api.client,
    entity="entity",
    project="project_name",
    filters=filters,
)

# Iterate over runs and print details
for run in runs:
    print(f"Run name: {run.name}")
    print(f"Run ID: {run.id}")
    print(f"Run URL: {run.url}")
    print(f"Run state: {run.state}")
    print(f"Run config: {run.config}")
    print(f"Run summary: {run.summary}")
    print(f"Run history (samples=5): {run.history(samples=5)}")
    print("----------")

# Get histories for all runs with specific metrics
histories_df = runs.histories(
    samples=100,  # Number of samples per run
    keys=["loss", "accuracy"],  # Metrics to fetch
    x_axis="_step",  # X-axis metric
    format="pandas",  # Return as pandas DataFrame
)

Methods

convert_objects

View source

convert_objects()

Converts GraphQL edges to Runs objects.

histories

View source

histories(
    samples: int = 500,
    keys: (list[str] | None) = None,
    x_axis: str = "_step",
    format: Literal['default', 'pandas', 'polars'] = "default",
    stream: Literal['default', 'system'] = "default"
)

Return sampled history metrics for all runs that fit the filters conditions.

next

View source

next() -> T

Return the next item from the iterator. When exhausted, raise StopIteration

update_variables

View source

update_variables() -> None

Update the query variables for the next page fetch.

upgrade_to_full

View source

upgrade_to_full()

Upgrade this Runs collection from lazy to full mode.

This switches to fetching full run data and upgrades any already-loaded Run objects to have full data. Uses parallel loading for better performance when upgrading multiple runs.

__getitem__

View source

__getitem__(
    index: (int | slice)
) -> (T | list[T])

__iter__

View source

__iter__() -> Iterator[T]

__len__

View source

__len__() -> int

20 - Sweep

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 Sweep

The set of runs associated with the sweep.

Attributes:

• runs (Runs): List of runs
• id (str): Sweep ID
• project (str): The name of the project the sweep belongs to
• config (dict): Dictionary containing the sweep configuration
• state (str): The state of the sweep. Can be “Finished”, “Failed”, “Crashed”, or “Running”.
• expected_run_count (int): The number of expected runs for the sweep

method Sweep.__init__

__init__(client, entity, project, sweep_id, attrs=None)

property Sweep.config

The sweep configuration used for the sweep.

property Sweep.entity

The entity associated with the sweep.

property Sweep.expected_run_count

Return the number of expected runs in the sweep or None for infinite runs.

Returns:

• int | None: The expected_run_count property value.

property Sweep.name

The name of the sweep.

Returns the first name that exists in the following priority order:

1. User-edited display name 2. Name configured at creation time 3. Sweep ID

property Sweep.order

Return the order key for the sweep.

property Sweep.path

Returns the path of the project.

The path is a list containing the entity, project name, and sweep ID.

property Sweep.url

The URL of the sweep.

The sweep URL is generated from the entity, project, the term “sweeps”, and the sweep ID.run_id. For SaaS users, it takes the form of https://wandb.ai/entity/project/sweeps/sweeps_ID.

property Sweep.username

Deprecated. Use Sweep.entity instead.

method Sweep.best_run

best_run(order=None)

Return the best run sorted by the metric defined in config or the order passed in.

classmethod Sweep.get

get(
    client: 'RetryingClient',
    entity: Optional[str] = None,
    project: Optional[str] = None,
    sid: Optional[str] = None,
    order: Optional[str] = None,
    query: Optional[str] = None,
    **kwargs
)

Execute a query against the cloud backend.

Args:

• client: The client to use to execute the query.
• entity: The entity (username or team) that owns the project.
• project: The name of the project to fetch sweep from.
• sid: The sweep ID to query.
• order: The order in which the sweep’s runs are returned.
• query: The query to use to execute the query.
• **kwargs: Additional keyword arguments to pass to the query.

method Sweep.to_html

to_html(height=420, hidden=False)

Generate HTML containing an iframe displaying this sweep.

21 - Sweeps

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 Sweeps

A lazy iterator over a collection of Sweep objects.

Examples:

from wandb.apis.public import Api

sweeps = Api().project(name="project_name", entity="entity").sweeps()

# Iterate over sweeps and print details
for sweep in sweeps:
    print(f"Sweep name: {sweep.name}")
    print(f"Sweep ID: {sweep.id}")
    print(f"Sweep URL: {sweep.url}")
    print("----------")

method Sweeps.__init__

__init__(
    client: wandb.apis.public.api.RetryingClient,
    entity: str,
    project: str,
    per_page: int = 50
) → Sweeps

An iterable collection of Sweep objects.

Args:

• client: The API client used to query W&B.
• entity: The entity which owns the sweeps.
• project: The project which contains the sweeps.
• per_page: The number of sweeps to fetch per request to the API.

property Sweeps.length

22 - Team

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 Team

A class that represents a W&B team.

This class provides methods to manage W&B teams, including creating teams, inviting members, and managing service accounts. It inherits from Attrs to handle team attributes.

method Team.__init__

__init__(client, name, attrs=None)

Args:

• client (wandb.apis.public.Api): The api instance to use
• name (str): The name of the team
• attrs (dict): Optional dictionary of team attributes

Note:

Team management requires appropriate permissions.

classmethod Team.create

create(api, team, admin_username=None)

Create a new team.

Args:

• api: (Api) The api instance to use
• team: (str) The name of the team
• admin_username: (str) optional username of the admin user of the team, defaults to the current user.

Returns: A Team object

method Team.create_service_account

create_service_account(description)

Create a service account for the team.

Args:

• description: (str) A description for this service account

Returns: The service account Member object, or None on failure

method Team.invite

invite(username_or_email, admin=False)

Invite a user to a team.

Args:

• username_or_email: (str) The username or email address of the user you want to invite.
• admin: (bool) Whether to make this user a team admin. Defaults to False.

Returns: True on success, False if user was already invited or didn’t exist.

23 - User

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 User

A class representing a W&B user with authentication and management capabilities.

This class provides methods to manage W&B users, including creating users, managing API keys, and accessing team memberships. It inherits from Attrs to handle user attributes.

method User.__init__

__init__(client, attrs)

Args:

• client: (wandb.apis.internal.Api) The client instance to use
• attrs: (dict) The user attributes

Note:

Some operations require admin privileges

property User.api_keys

List of API key names associated with the user.

Returns:

• list[str]: Names of API keys associated with the user. Empty list if user has no API keys or if API key data hasn’t been loaded.

property User.teams

List of team names that the user is a member of.

Returns:

• list (list): Names of teams the user belongs to. Empty list if user has no team memberships or if teams data hasn’t been loaded.

property User.user_api

An instance of the api using credentials from the user.

classmethod User.create

create(api, email, admin=False)

Create a new user.

Args:

• api (Api): The api instance to use
• email (str): The name of the team
• admin (bool): Whether this user should be a global instance admin

Returns: A User object

method User.delete_api_key

delete_api_key(api_key)

Delete a user’s api key.

Args:

• api_key (str): The name of the API key to delete. This should be one of the names returned by the api_keys property.

Returns: Boolean indicating success

Raises: ValueError if the api_key couldn’t be found

method User.generate_api_key

generate_api_key(description=None)

Generate a new api key.

Args:

• description (str, optional): A description for the new API key. This can be used to identify the purpose of the API key.

Returns: The new api key, or None on failure