Api

Used for querying the wandb server.

Api(
    overrides: Optional[Dict[str, Any]] = None,
    timeout: Optional[int] = None,
    api_key: Optional[str] = None
) -> None

Examples:

Most common way to initialize

>>> wandb.Api()

Methods

artifact

View source

artifact(
    name: str,
    type: Optional[str] = None
)

Return a single artifact by parsing path in the form project/name or entity/project/name.

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
) -> "public.ArtifactCollection"

Return a single artifact collection by type and parsing path in the form entity/project/name.

artifact_collection_exists

View source

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

Return whether an artifact collection exists within a specified project and entity.

artifact_collections

View source

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

Return a collection of matching artifact collections.

artifact_exists

View source

artifact_exists(
    name: str,
    type: Optional[str] = None
) -> bool

Return whether an artifact version exists within a specified project and entity.

artifact_type

View source

artifact_type(
    type_name: str,
    project: Optional[str] = None
) -> "public.ArtifactType"

Return the matching ArtifactType.

artifact_types

View source

artifact_types(
    project: Optional[str] = None
) -> "public.ArtifactTypes"

Return a collection of matching artifact types.

artifact_versions

View source

artifact_versions(
    type_name, name, per_page=50
)

Deprecated, use artifacts(type_name, name) instead.

artifacts

View source

artifacts(
    type_name: str,
    name: str,
    per_page: int = 50,
    tags: Optional[List[str]] = None
) -> "public.Artifacts"

Return an Artifacts collection from the given parameters.

automation

View source

automation(
    name: str,
    *,
    entity: Optional[str] = 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: Optional[str] = None,
    *,
    name: Optional[str] = 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_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: Optional[str] = None,
    description: Optional[str] = None,
    artifact_types: Optional[List[str]] = 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: Optional[str] = None,
    project: Optional[str] = None,
    entity: Optional[str] = None
) -> "public.Run"

Create a new run.

create_run_queue

View source

create_run_queue(
    name: str,
    type: "public.RunQueueResourceType",
    entity: Optional[str] = None,
    prioritization_mode: Optional['public.RunQueuePrioritizationMode'] = None,
    config: Optional[dict] = None,
    template_variables: Optional[dict] = None
) -> "public.RunQueue"

Create a new run queue (launch).

create_team

View source

create_team(
    team, admin_username=None
)

Create a new team.

create_user

View source

create_user(
    email, admin=(False)
)

Create a new user.

delete_automation

View source

delete_automation(
    obj: Union['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
)

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

Examples:

project = api.from_path("my_project")
team_project = api.from_path("my_team/my_project")
run = api.from_path("my_team/my_project/runs/id")
sweep = api.from_path("my_team/my_project/sweeps/id")
report = api.from_path("my_team/my_project/reports/My-Report-Vm11dsdf")

integrations

View source

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

Return an iterator of all integrations for an entity.

job

View source

job(
    name: Optional[str],
    path: Optional[str] = None
) -> "public.Job"

Return a Job from the given parameters.

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: Optional[str] = None
) -> "public.Project"

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

projects

View source

projects(
    entity: Optional[str] = None,
    per_page: int = 200
) -> "public.Projects"

Get projects for a given entity.

queued_run

View source

queued_run(
    entity, project, queue_name, run_queue_item_id, 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: Optional[str] = None,
    filter: Optional[Dict[str, Any]] = None
) -> Registries

Returns a Registry iterator.

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: Optional[str] = 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: Optional[str] = None,
    per_page: int = 50
) -> "public.Reports"

Get reports for a given project path.

WARNING: This api is in beta and will likely change in a future release

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, name
)

Return the named RunQueue for entity.

To create a new RunQueue, use wandb.Api().create_run_queue(...).

runs

View source

runs(
    path: Optional[str] = None,
    filters: Optional[Dict[str, Any]] = None,
    order: str = "+created_at",
    per_page: int = 50,
    include_sweeps: bool = (True)
)

Return a set of runs from a project that match the filters provided.

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 my_project where config.experiment_name has been set to “foo”

api.runs(
    path="my_entity/my_project",
    filters={"config.experiment_name": "foo"},
)

Find runs in my_project where config.experiment_name has been set to “foo” or “bar”

api.runs(
    path="my_entity/my_project",
    filters={
        "$or": [
            {"config.experiment_name": "foo"},
            {"config.experiment_name": "bar"},
        ]
    },
)

Find runs in my_project where config.experiment_name matches a regex (anchors are not supported)

api.runs(
    path="my_entity/my_project",
    filters={"config.experiment_name": {"$regex": "b.*"}},
)

Find runs in my_project where the run name matches a regex (anchors are not supported)

api.runs(
    path="my_entity/my_project",
    filters={"display_name": {"$regex": "^foo.*"}},
)

Find runs in my_project where config.experiment contains a nested field “category” with value “testing”

api.runs(
    path="my_entity/my_project",
    filters={"config.experiment.category": "testing"},
)

Find runs in my_project with a loss value of 0.5 nested in a dictionary under model1 in the summary metrics

api.runs(
    path="my_entity/my_project",
    filters={"summary_metrics.model1.loss": 0.5},
)

Find runs in my_project sorted by ascending loss

api.runs(path="my_entity/my_project", order="+summary_metrics.loss")

slack_integrations

View source

slack_integrations(
    *,
    entity: Optional[str] = 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
) -> "public.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: ```python 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](https://www.github.com/wandb/wandb/tree/v0.19.11/wandb/apis/public/api.py#L466-L579)

```python
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['public.RunQueuePrioritizationMode'] = None
)

Upsert a run queue (launch).

user

View source

user(
    username_or_email: str
) -> Optional['public.User']

Return a user from a username or email address.

Note: This function only works for Local Admins, if you are trying to get your own user object, please use api.viewer.

users

View source

users(
    username_or_email: str
) -> List['public.User']

Return all users from a partial username or email address query.

Note: This function only works for Local Admins, if you are trying to get your own user object, please use api.viewer.

webhook_integrations

View source

webhook_integrations(
    entity: Optional[str] = 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")
]