API

The API class is used as a Python interface to the Comet.ml Python API.

You can use an instance of the API() class to quickly and easily access all of your logged information at comet, including metrics, parameters, tags, and assets.

Example calls to get workspace, project, and experiment data:

API.get(): gets all of your personal workspaces
API.get(WORKSPACE): gets all of your projects from WORKSPACE
API.get(WORKSPACE, PROJECT_NAME): get all APIExperiments in WORKSPACE/PROJECT
API.get_experiment(WORKSPACE, PROJECT_NAME, EXPERIMENT_KEY): get an APIExperiment
API.get_experiment("WORKSPACE/PROJECT_NAME/EXPERIMENT_KEY"): get an APIExperiment
API.get_experiments(WORKSPACE): get all APIExperiments in WORKSPACE
API.get_experiments(WORKSPACE, PROJECT_NAME): get all APIExperiments in WORKSPACE/PROJECT
API.get_experiments(WORKSPACE, PROJECT_NAME, PATTERN): get all APIExperiments in WORKSPACE/PROJECT/PATTERN

Examples:

>>> import comet_ml
>>> api = comet_ml.api.API()

## Return all of my workspace names in a list:
>>> api.get()

## Get an APIExperiment:
>>> experiment = api.get("cometpublic/comet-notebooks/example 001")

## Get metrics:
>>> experiment.get_metrics("train_accuracy")

The API instance also gives you access to the low-level Python API function calls:

>>> api.delete_experiment(experiment_key)

For more usage examples, see Comet Python API examples.

API.init¶

__init__(api_key=None, cache=True, version="v2")

Application Programming Interface to the Comet Python interface.

Args:

api_key: Optional. Your private COMET_API_KEY.
cache: Bool, whether to cache on values or not.
version: Optional. The version of the REST API to use.

Note: api_key may be defined in environment (COMET_API_KEY) or in a .comet.config file.

Example:

>>> from comet_ml.api import API
>>> api = API(api_key="08ac6a75a2be4d7c9aac2c39e0004f6e")
>>> api.get("my-workspace")
['project1', 'project2', ...]

API.add_registry_model_version_stage¶

add_registry_model_version_stage(workspace, registry_name, version, stage)

Adds a stage to a registered model version.

This method has been deprecated as stage has been replaced by status and a new Model object was introduced. We recommend using the api.get_model(...) method to get the Model object and then using model.set_status(version='', status='')

Args:

workspace: str, the name of the workspace
registry_name: str, the name of the model
version: str, version of model to update
stage: str, "production", or "staging", etc.

API.archive_experiment¶

archive_experiment(experiment_key)

Archive one experiment.

Args:

experiment_key: the experiment ID to archive

API.archive_experiments¶

archive_experiments(experiment_keys)

Archive list of experiments.

Args:

experiment_keys: the experiment IDs to archive

API.clear_cache¶

clear_cache()

Used when cache is on, but you have added/changed data outside of this API instance.

Note: you could also just start with no cache.

>>> api = API(cache=False)

Or, if you had started with cache, turn it off:

>>> api = API(cache=True)
>>> api.do_cache(False)

API.create_project¶

create_project(workspace, project_name, project_description=None,
    public=False)

Create a project.

API.create_project_share_key¶

create_project_share_key(project_id)

Get the share keys for a private project ID.

Args:

project_id: String, the ID of the project

Example:

>>> api = API()
>>> SHARE_KEY = api.create_project_share_key(PROJECT_ID)

See also: API.get_project_share_keys(), and API.delete_project_share_key().

API.delete_experiment¶

delete_experiment(experiment_key)

Delete one experiment.

API.delete_experiments¶

delete_experiments(experiment_keys)

Delete list of experiments.

Args:

experiment_keys: a list of experiment keys to delete.

API.delete_project¶

delete_project(workspace=None, project_name=None, project_id=None,
    delete_experiments=False)

Delete a project.

Args:

workspace: the name of the workspace (required if project_id not given)
project_name: the name of the project (required if project_id not given)
project_id: the project id (required, if workspace and project name not given)
delete_experiments: if True, delete all of the experiments, too

API.delete_project_share_key¶

delete_project_share_key(project_id, share_key)

Delete a share key for a private project ID.

Args:

project_id: String, the ID of the project
share_key: String, the share key to delete

Example:

>>> api = API()
>>> SHARE_KEYS = api.get_project_share_keys(PROJECT_ID)
>>> api.delete_project_share_key(PROJECT_ID, SHARE_KEYS[0])

See also: API.get_project_share_keys(), and API.create_project_share_key().

API.delete_registry_model¶

delete_registry_model(workspace, registry_name)

Deletes a registered model.

Args:

workspace: str, the name of the workspace
registry_name: str, the name of the model

API.delete_registry_model_version¶

delete_registry_model_version(workspace, registry_name, version)

Deletes a registered model version.

Args:

workspace: str, the name of the workspace
registry_name: str, the name of the model
version: str, version of model to update

API.delete_registry_model_version_stage¶

delete_registry_model_version_stage(workspace, registry_name, version,
    stage)

Removes a stage from a registered model version.

This method has been deprecated as stage has been replaced by status and a new Model object was introduced. We recommend using the api.get_model(...) method to get the Model object and then using model.set_status(version='', status=None)

Args:

workspace: str, the name of the workspace
registry_name: str, the name of the model
version: str, version of model to update
stage: str, "production", or "staging", etc.

API.do_cache¶

do_cache(*endpoints)

Cache the given endpoints.

Example:

>>> from comet_ml.api import API
>>> api = API()
>>> api.do_cache("experiments", "projects")

API.do_not_cache¶

do_not_cache(*endpoints)

Do not cache the given endpoints.

Example:

>>> from comet_ml.api import API
>>> api = API()
>>> api.do_not_cache("experiments", "projects")

API.download_experiment_asset¶

download_experiment_asset(experiment_key, asset_id, output_path)

Download an experiment (or a model registry) asset to the specified output_path.

Args:

experiment_key: str, the experiment unique key to download from
asset_id: str, the asset ID
output_path: str, where to download the asset

Raises a comet_ml.exceptions.CometRestApiException: if the asset or experiment_key is not found.

Raises a OSError: if the asset cannot be written to the output_path.

API.download_registry_model¶

download_registry_model(workspace, registry_name, version=None,
    output_path="./", expand=True, stage=None)

Download and save all files from the registered model.

This method has been deprecated as stage has been replaced by status and a new Model object was introduced. We recommend using the api.get_model(...) method to get the Model object and then using model.download(...)

Args:

workspace: str, the name of the workspace
registry_name: str, the name of the model
version: str, version string of the model
output_path: optional, str, the output directory; defaults to current directory
expand: if True, the downloaded zipfile is unzipped; if False, then the zipfile is copied to the output_path
stage: optional, a textual tag such as "production" or "staging"

API.gen_experiments¶

gen_experiments(workspace, project_name=None, pattern=None)

Get APIExperiments by workspace, workspace + project, or workspace + project + regular expression pattern.

API.get¶

get(workspace=None, project_name=None, experiment=None)

Get the following items:

list of workspace names, given no arguments
list of project names, given a workspace name
list of experiment names/keys, given workspace and project names
an experiment, given workspace, project, and experiment name/key

workspace, project_name, and experiment can also be given as a single string, delimited with a slash.

API.get_account_details¶

get_account_details()

Return the username and the default workspace name for the authorized user.

Returns:

{
 'userName': 'USERNAME',
 'defaultWorkspaceName': 'WORKSPACE',
}

API.get_archived_experiment¶

get_archived_experiment(workspace, project_name, experiment)

Get a single archived APIExperiment by workspace, project, experiment.

API.get_archived_experiments¶

get_archived_experiments(workspace, project_name=None, pattern=None)

Get archived APIExperiments by workspace, workspace + project, or workspace + project + regular expression pattern.

API.get_artifact_details¶

get_artifact_details(workspace=None, artifact_name=None, artifact_id=None)

Returns the details of a single artifact identified either by the workspace name + the artifact name or by its unique artifact ID.

Args:

workspace: String - Optional, the name of the workspace
artifact_name: String - Optional, the name of the artifact
artifact_id: String - Optional, the unique ID of the artifact, for example 6194e719-f596-48e7-8cca-8530c16dd007

>>> api.get_artifact_details("demo", "demo-artifact")
{'artifactId': '6194e719-f596-48e7-8cca-8530c16dd007',
    'project': 'demo-artifacts',
    'type': 'dataset',
    'name': 'demo-artifact',
    'description': None,
    'latestVersion': '2.0.0',
    'tags': [],
    'isPublic': False,
    'emoji': None,
    'sizeInBytes': 21113,
    'versions': [{'artifactVersionId': 'a8286090-c637-4270-99ab-25b18676a035',
            'version': '1.0.0',
            'owner': 'lothiraldan',
            'metadata': None,
            'createdFrom': None,
            'sizeInBytes': 0,
            'state': None,
            'added': 1621948911721,
            'alias': ['current-production'],
            'tags': ['production']},
        {'artifactVersionId': 'bf778c64-a97c-4bff-9752-7fa6bfebbe2e',
            'version': '2.0.0',
            'owner': 'lothiraldan',
            'metadata': None,
            'createdFrom': None,
            'sizeInBytes': 21113,
            'state': None,
            'added': 1621948972987,
            'alias': ['Latest'],
            'tags': ['staging']}]}

API.get_artifact_files¶

get_artifact_files(workspace=None, artifact_name=None, artifact_id=None,
    version=None, alias=None)

Returns the files of a single artifact version. The artifact is identified either by the workspace name + the artifact name or by its unique artifact ID. The artifact version is identified either by an explicit version or by an explicit alias.

Args:

workspace: String - Optional, the name of the workspace
artifact_name: String - Optional, the name of the artifact
artifact_id: String - Optional, the unique ID of the artifact, for example 6194e719-f596-48e7-8cca-8530c16dd007
version: String - Optional, the version number of the artifact version you want
alias: String - Optiona, the alias of the artifact version you want

>>> api.get_artifact_files("demo", artifact_name="demo-artifact", version="2.0.0")
{'files': [{'artifactId': '6194e719-f596-48e7-8cca-8530c16dd007',
    'artifactVersionId': 'bf778c64-a97c-4bff-9752-7fa6bfebbe2e',
    'assetId': '6aa914ffbee94e11b69445383d7732f4',
    'fileName': 'logo.png',
    'fileSize': 21113,
    'link': None,
    'dir': None,
    'type': 'unknown',
    'metadata': None}]}

>>> api.get_artifact_files("demo", artifact_name="demo-artifact", alias="current-production")
{'files': [{'artifactId': '6194e719-f596-48e7-8cca-8530c16dd007',
    'artifactVersionId': 'a8286090-c637-4270-99ab-25b18676a035',
    'assetId': 'dea243de41714a48961f725dbbe4d214',
    'fileName': 'file',
    'fileSize': 0,
    'link': 's3://bucket/dir/file',
    'dir': None,
    'type': 'unknown',
    'metadata': None}]}

API.get_artifact_list¶

get_artifact_list(workspace, artifact_type=None)

Return the list of artifacts in a given workspace. Could be optionally filtered by a specific type.

Args:

workspace: String, the name of the workspace
artifact_type: String - Optional, if provided only returns Artifacts with the given type

>>> api.get_artifact_list("demo")
{'artifacts': [{'artifactId': '6194e719-f596-48e7-8cca-8530c16dd007',
    'project': 'demo-artifacts',
    'type': 'dataset',
    'name': 'demo-artifact',
    'description': None,
    'versionsCount': 2,
    'tags': [],
    'isPublic': False,
    'emoji': None,
    'sizeInBytes': 21113}]}

API.get_default_workspace¶

get_default_workspace()

Get the default workspace name.

Example:

>>> api = API()
>>> workspace = api.get_default_workspace()

API.get_experiment¶

get_experiment(workspace, project_name, experiment)

Get a single APIExperiment by workspace, project, experiment.

API.get_experiment_by_id¶

get_experiment_by_id(experiment)

API.get_experiment_by_key¶

get_experiment_by_key(experiment_key)

Get an APIExperiment by experiment key.

API.get_experiments¶

get_experiments(workspace, project_name=None, pattern=None)

Get APIExperiments by workspace, workspace + project, or workspace + project + regular expression pattern.

API.get_latest_registry_model_version_details¶

get_latest_registry_model_version_details(workspace: str,
    registry_name: str, stage: Optional[str] = None,
    version_major: Optional[int] = None,
    version_minor: Optional[int] = None) -> Dict[str, Any]

Return details about the latest model registry version, including its asset list.

This method has been deprecated as stage has been replaced by status and a new Model object was introduced. We recommend using the api.get_model(...) method to get the Model object and then using model.find_versions(...)

Args:

workspace: str, the name of the workspace
registry_name: str, the name of the model
version_major: int, the major part of version string of the model
version_minor: int, the minor part of version string of the model
stage: optional, a textual tag such as "production" or "staging"

Example:

>>> from comet_ml import API
>>> api = API()
>>> api_exp = api.get("workspace/project/765643463546345364536453436")
>>> api_exp.get_latest_registry_model_version_details("myworkspace", "model-name")
{
    "registryModelId": "someRegistryModelId",
    "modelName": "someModelName",
    "description": "someDescription",
    "isPublic": "[Boolean]",
    "createdAt": "[long, when this model was created in the DB]",
    "lastUpdated": "[long, last time this model was updated in the DB]",
    "userName": "someUserName",
    "versions": [
        {
            "registryModelItemId": "someRegistryModelItemId",
            "experimentModel": {
                "experimentModelId": "someExperimentModelId",
                "experimentModelName": "someExperimentModelName",
                "experimentKey": "someExperimentKey"
            },
            "version": "someVersion",
            "comment": "someComment",
            "stages": [
                "production",
                "staging"
            ],
            "userName": "someUserName",
            "createdAt": "[long, when this model item was created in the DB]",
            "lastUpdated": "[long, last time this model item was updated in the DB]",
            "assets": [
                {
                    "fileName": "someFileName",
                    "fileSize": "[Long, file size]",
                    "runContext": "someRunContext",
                    "step": "[Integer, step asset was logged during]",
                    "link": "link to download asset file",
                    "createdAt": "[Long, timestamp asset was created in DB]",
                    "dir": "someDirectory",
                    "canView": "[Boolean, whether the asset is viewable as an image]",
                    "audio": "[Boolean, whether the asset is an audio file]",
                    "histogram": "[Boolean, whether the asset is a histogram file]",
                    "image": "[Boolean, whether the asset was stored as an image]",
                    "type": "the type of asset",
                    "metadata": "Metadata associated with the asset",
                    "assetId": "someAssetId"
                }
            ]
        }
    ]
}

API.get_metrics_for_chart¶

get_metrics_for_chart(experiment_keys, metrics=None, parameters=None,
    independent=True, full=False)

Get multiple metrics and parameters from a set of experiments. This method is designed to make custom charting easier.

Args:

experiment_keys: a list of experiment keys
metrics: an optional list of metric names (e.g., "loss")
parameters: an optional list of parameter names (e.g., "learning-rate")
independent: Bool, get independent results?
full: Bool, fetch the full result?

Note: you should pass in a list of metric names, or a list of parameter names, or both.

Returns: a dictionary of experiment keys with the following structure. {EXPERIMENT_KEY: {'params'} will be None if there are no parameters passed in.

>>> from comet_ml.api import API
>>> api = API()
>>> api.get_metrics_for_chart([experiment_key1, experiment_key2, ...],
                                    ["loss"], ["hidden_layer_size"])
{EXPERIMENT_KEY: {
   'experiment_key': EXPERIMENT_KEY,
   'steps': STEPS,
   'epochs': None,
   'metrics': [
      {'metricName': 'loss',
       'values': [VALUE, ...],
       'steps': [STEP, ...],
       'epochs': [EPOCH, ...],
       'timestamps': [TIMESTAMP, ...],
       'durations': [DURATION, ...],
      }],
   'params': {'hidden_layer_size': VALUE, ...},
}, ...}

API.get_model¶

get_model(workspace: str, model_name: str) -> model.Model

Get a Model API object corresponding to a given model

Args:

workspace: the name of workspace
model_name: the name of registered model

API.get_model_registry_version_assets¶

get_model_registry_version_assets(workspace, registry_name, version=None,
    stage=None)

Return details about a single model registry version, including its asset list.

This method has been deprecated as stage has been replaced by status and a new Model object was introduced. We recommend using the api.get_model(...) method to get the Model object and then using model.get_assets(...)

Args:

workspace: str, the name of the workspace
registry_name: str, the name of the model
version: str, version string of the model
stage: optional, a textual tag such as "production" or "staging"

Example:

>>> from comet_ml import API
>>> api = API()
>>> api_exp = api.get("workspace/project/765643463546345364536453436")
>>> api_exp.get_model_registry_version_assets("myworkspace", "model-name")
{
    "registryModelItemId": "someRegistryModelItemId",
    "experimentModel": {
        "experimentModelId": "someExperimentModelId",
        "experimentModelName": "someExperimentModelName",
        "experimentKey": "someExperimentKey"
    },
    "version": "someVersion",
    "comment": "someComment",
    "stages": ["production", "staging"],
    "userName": "someUserName",
    "createdAt": "[long, when this model item was created in the DB]",
    "lastUpdated": "[long, last time this model item was updated in the DB]",
    "assets": [
        {
            "fileName": "someFileName",
            "fileSize": "[Long, file size]",
            "runContext": "someRunContext",
            "step": "[Integer, step asset was logged during]",
            "link": "link to download asset file",
            "createdAt": "[Long, timestamp asset was created in DB]",
            "dir": "someDirectory",
            "canView": "[Boolean, whether the asset is viewable as an image]",
            "audio": "[Boolean, whether the asset is an audio file]",
            "histogram": "[Boolean, whether the asset is a histogram file]",
            "image": "[Boolean, whether the asset was stored as an image]",
            "type": "the type of asset",
            "metadata": "Metadata associated with the asset",
            "assetId": "someAssetId",
        }
    ],
}