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.ml, 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:

```python

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:

```python

api.delete_experiment(experiment_key) ```

For more usage examples, see Comet Python API examples.

API.server_url¶

API.`init`¶

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

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:

```python

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

API.add_registry_model_version_stage¶

python add_registry_model_version_stage(self, workspace, registry_name, version, stage)

Adds a stage to 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
stage: str, "production", or "staging", etc.

API.archive_experiment¶

python archive_experiment(self, experiment_key)

Archive one experiment.

Args:

experiment_key: the experiment ID to archive

API.archive_experiments¶

python archive_experiments(self, experiment_keys)

Archive list of experiments.

Args:

experiment_keys: the experiment IDs to archive

API.clear_cache¶

python clear_cache(self)

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.

```python

api = API(cache=False) ```

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

```python

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

API.create_project¶

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

Create a project.

API.create_project_share_key¶

python create_project_share_key(self, project_id)

Get the share keys for a private project ID.

Args:

project_id: String, the ID of the project

Example:

```python

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¶

python delete_experiment(self, experiment_key)

Delete one experiment.

API.delete_experiments¶

python delete_experiments(self, experiment_keys)

Delete list of experiments.

Args:

experiment_keys: a list of experiment keys to delete.

API.delete_project¶

python delete_project(self, 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¶

python delete_project_share_key(self, 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:

```python

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¶

python delete_registry_model(self, 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¶

python delete_registry_model_version(self, 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¶

python delete_registry_model_version_stage(self, workspace, registry_name, version, stage)

Removes a stage from 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
stage: str, "production", or "staging", etc.

API.do_cache¶

python do_cache(self, *endpoints)

Cache the given endpoints.

Example:

```python

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

API.do_not_cache¶

python do_not_cache(self, *endpoints)

Do not cache the given endpoints.

Example:

```python

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

API.download_experiment_asset¶

python download_experiment_asset(self, 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¶

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

Download and save all files from the registered model.

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¶

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

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

API.get¶

python get(self, 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¶

python get_account_details(self)

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

Returns:

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

API.get_archived_experiment¶

python get_archived_experiment(self, workspace, project_name, experiment)

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

API.get_archived_experiments¶

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

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

API.get_artifact_details¶

python get_artifact_details(self, 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

```python

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¶

python get_artifact_files(self, 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

```python

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¶

python get_artifact_list(self, 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

```python

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¶

python get_default_workspace(self)

Get the default workspace name.

Example:

```python

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

API.get_experiment¶

python get_experiment(self, workspace, project_name, experiment)

Get a single APIExperiment by workspace, project, experiment.

API.get_experiment_by_id¶

python get_experiment_by_id(self, experiment)

API.get_experiment_by_key¶

python get_experiment_by_key(self, experiment_key)

Get an APIExperiment by experiment key.

API.get_experiments¶

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

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

API.get_metrics_for_chart¶

python get_metrics_for_chart(self, 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.

```python

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_registry_version_assets¶

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

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

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:

```python

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", } ], } ```