Read Endpoints

Note that access to the Comet REST endpoints require the {'Authorization': ${COMET_API_KEY}} header. To get your API key, see Comet Python API Setup.

Get User Workspaces

GET /api/rest/v2/workspaces

Get a user's workspaces.

Example Response

{
    "workspaceNames": [
        "team name",
        "another team name"
    ]
}

---

Get Projects

GET /api/rest/v2/projects?workspaceName=aTeamName

Get a workspace's projects.

Example Response

{
    "projects": [
        {
            "isPublic": "[boolean, true if this is a public project]",
            "lastUpdated": "[long, last time this project was updated in the DB]",
            "numberOfExperiments": "[integer, number of experiments in this project]",
            "ownerUserName": "Owner User Name",
            "projectDescription": "Project Description",
            "projectId": "aProjectId",
            "projectName": "Project Name",
            "workspaceId": "Team/workspace this project is in",
            "workspaceName": "Name of the team for team_id above"
        }
    ]
}

---

Get Registry Models

GET /api/rest/v2/registry-model?workspaceName=aTeamName

Get a workspace's registry models.

Example Response

{
    "registryModels": [
        {
            "createdAt": "[long, when this model was created in the DB]",
            "description": "someDescription",
            "isPublic": "[Boolean]",
            "lastUpdated": "[long, last time this model was updated in the DB]",
            "latestVersion": {
                "comment": "someComment",
                "createdAt": "[long, when this model item was created in the DB]",
                "experimentModel": {
                    "experimentKey": "someExperimentKey",
                    "experimentModelId": "someExperimentModelId",
                    "experimentModelName": "someExperimentModelName"
                },
                "lastUpdated": "[long, last time this model item was updated in the DB]",
                "metadata": [
                    "metadata from first asset",
                    "metadata from second asset"
                ],
                "registryModelItemId": "someRegistryModelItemId",
                "stages": [
                    "production",
                    "staging"
                ],
                "userName": "someUserName",
                "version": "someVersion"
            },
            "modelName": "someModelName",
            "registryModelId": "someRegistryModelId",
            "userName": "someUserName"
        }
    ]
}

---

Get Registry Model Count

GET /api/rest/v2/registry-model/count?workspaceName=aTeamName

Get a count of a workspace's registry models.

Example Response

{
    "registryModelCount": 7
}

---

Get Registry Model Details

GET /api/rest/v2/registry-model/details?workspaceName=someWorkspaceName&modelName=someModelName

Get a registry model's details.

Example Response

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

---

Get Registry Model Notes

GET /api/rest/v2/registry-model/notes?workspaceName=someWorkspaceName&modelName=someModelName

Get a registry model's notes.

Example Response

{
    "notes": "Potentially very long notes string"
}

---

Download Registry Model Version

GET /api/rest/v2/registry-model/item/download?workspaceName=someWorkspaceName&modelName=someModelName&version=someVersion

Download a zip file of a registry model version.

Example Response

"[Raw stream of zip file as octet-stream]"

---

Get Project

GET /api/rest/v2/project?projectId=someProjectId

GET /api/rest/v2/project?projectName=pname&workspaceName=aTeamName

Get details on a project.

Example Response

{
    "isPublic": "[boolean, true if this is a public project]",
    "lastUpdated": "[long, last time this project was updated in the DB]",
    "numberOfExperiments": "[integer, number of experiments in this project]",
    "ownerUserName": "Owner User Name",
    "projectDescription": "Project Description",
    "projectId": "aProjectId",
    "projectName": "Project Name",
    "workspaceId": "Team/workspace this project is in",
    "workspaceName": "Name of the team for team_id above"
}

---

Get Experiments

GET /api/rest/v2/experiments?projectId=someProjectId&archived=false

GET /api/rest/v2/experiments?projectName=pname&workspaceName=wsname&archived=false

Get a project's experiments.

Example Response

{
    "experiments": [
        {
            "durationMillis": "[long, How long the experiment ran for]",
            "endTimeMillis": "[long, As recorded by the backend, when this experiment ended]",
            "experimentKey": "SomeExperimentKey",
            "experimentName": "SomeExperimentName",
            "optimizationId": "optimization run associated with this experiment, if any",
            "startTimeMillis": "[long, As recorded by the backend, when this experiment started]"
        }
    ]
}

---

Get Project Columns

GET /api/rest/v2/project/column-names?projectId=someProjectId&archived=false

GET /api/rest/v2/project/column-names?projectName=pname&workspaceName=ws&archived=false

Get a project's columns. These are the items that can be queried.

Example Response

{
    "columns": [
        {
            "id": "unique-column-id",
            "name": "Column Name",
            "source": "one of: metrics, params, log_other, metadata, tag, or env_details",
            "type": "one of: double, string, datetime, boolean, or timenumber"
        }
    ]
}

---

Apply Project Query

POST /api/rest/v2/project/query

Apply a query to a project.

Example Request

{
    "archived": "[boolean: if true search for archived experiments.  Optional]",
    "predicates": "Json Predicates for search here, example below",
    "projectId": "someProjectId",
    "projectName": "someProjectName",
    "workspaceName": "someWorkspaceName"
}

Example Response

{
    "experimentKeys": [
        "KEY",
        "anotherExperimentKey"
    ],
    "experimentsInProject": "[int count of experiments in project, including all those filtered out.  If archived was true this is the archived experiment count]"
}

Note: An example predicate:

[
    {
      "source": "metrics",
      "query": {
        "condition": "AND",
        "rules": [
          {
            "id": "columnNameA",
            "field": "columnNameA",
            "type": "double",
            "input": "text",
            "operator": "greater",
            "value": 1
          }
        ],
        "valid": true
      }
    }
  ]

---

Get Project Notes

GET /api/rest/v2/project/notes?projectId=PROJECTID

Get a project's notes.

Example Response

{
    "notes": "someProjectNotes"
}

---

Get Multi Metric Chart

POST /api/rest/v2/experiments/multi-metric-chart

Get multi-metric chart data.

Example Request

{
    "fetchFull": "[Boolean, whether to fetch all values (up to 15,000) or a sampled subset (about 500 points)]",
    "independentMetrics": "[Boolean, whether the metrics should be fetched individually or as a correlated whole (only return values for steps for which you have values for every requested metric name)]",
    "metrics": [
        "someMetricName",
        "anotherMetricName"
    ],
    "params": [
        "someParameterName",
        "anotherParameterName"
    ],
    "targetedExperiments": [
        "KEY",
        "anotherExperimentKey"
    ]
}

Example Response

{
    "empty": "[Boolean, whether any metrics were returned]",
    "experiments": {
        "KEY": {
            "experimentKey": "KEY",
            "metrics": [
                {
                    "durations": [
                        "[Long, time between each value and the previous value, 0 for the first]"
                    ],
                    "metricName": "someMetricName",
                    "steps": [
                        1,
                        2,
                        3
                    ],
                    "timestamps": [
                        "[Long, list of timestamps of metric values]"
                    ],
                    "values": [
                        1.2,
                        1.3,
                        1.4
                    ]
                }
            ],
            "params": {
                "anotherParam": "whatever value you want",
                "someParam": "8675309"
            },
            "steps": [
                1,
                2,
                3
            ]
        }
    }
}

---

Get Experiment Metadata

GET /api/rest/v2/experiment/metadata?experimentKey=KEY

Get an experiment's metadata.

Example Response

{
    "durationMillis": "someDurationMillis",
    "endTimeMillis": "someEndTimeMillis",
    "experimentKey": "KEY",
    "experimentName": "someExperimentName",
    "optimizationId": "someOptimizationId",
    "projectId": "someProjectId",
    "projectName": "someProjectName",
    "startTimeMillis": "someStartTimeMillis",
    "workspaceName": "someWorkspaceName"
}

---

Get Git Metadata

GET /api/rest/v2/experiment/git/metadata?experimentKey=KEY

Get the git metadata of an experiment.

Example Response

{
    "branch": "gitBranch",
    "origin": "gitOrigin",
    "parent": "gitParent",
    "root": "gitRoot",
    "user": "gitUser"
}

---

Get Git Patch

GET /api/rest/v2/experiment/git/patch?experimentKey=KEY

Get the git patch of an experiment.

Example Response

"[Raw stream of git patch as octet-stream]"

---

Get Html

GET /api/rest/v2/experiment/html?experimentKey=KEY

Get an experiment's HTML.

Example Response

{
    "html": "Html for Experiment"
}

---

Get Code

GET /api/rest/v2/experiment/code?experimentKey=KEY

Get an experiment's source code.

Example Response

{
    "code": "Code for Experiment"
}

---

Get Output

GET /api/rest/v2/experiment/output?experimentKey=KEY

Get an experiment's standard output and error.

Example Response

{
    "output": "stdout and stderr output for Experiment, with '\n' delimiters"
}

---

Get Graph

GET /api/rest/v2/experiment/graph?experimentKey=KEY

Get an experiment's model graph.

Example Response

{
    "graph": "Graph for Experiment"
}

---

Get All Metrics For Name

GET /api/rest/v2/experiment/metrics/get-metric?experimentKey=KEY&metricName=NAME

Get all metric values for a metric name.

Example Response

{
    "metrics": [
        {
            "epoch": "[long, epoch this metric is from]",
            "metricName": "someMetricName",
            "metricValue": "someMetricValue",
            "offset": "[Long, offset that this metric was sent as]",
            "runContext": "someRunContext",
            "step": "[long, step this metric is from]",
            "timestamp": "[long, time this metric was recorded]"
        }
    ]
}

---

Get Metrics Summary

GET /api/rest/v2/experiment/metrics/summary?experimentKey=KEY

Get an experiment's metrics summary.

Example Response

{
    "values": [
        {
            "name": "someName",
            "runContextCurrent": "run context of last value",
            "runContextMax": "run context of max value",
            "runContextMin": "run context of min value",
            "stepCurrent": "[long, step current value is from]",
            "stepMax": "[long, step max value is from]",
            "stepMin": "[long, step min value is from]",
            "timestampCurrent": "[long, time last value was recorded]",
            "timestampMax": "[long, time max value was recorded]",
            "timestampMin": "[long, time min value was recorded]",
            "valueCurrent": "last value",
            "valueMax": "max value",
            "valueMin": "min value"
        }
    ]
}

---

Get Parameters

GET /api/rest/v2/experiment/parameters?experimentKey=KEY

Get an experiment's parameters summary.

Example Response

{
    "values": [
        {
            "name": "someName",
            "runContextCurrent": "run context of last value",
            "runContextMax": "run context of max value",
            "runContextMin": "run context of min value",
            "stepCurrent": "[long, step current value is from]",
            "stepMax": "[long, step max value is from]",
            "stepMin": "[long, step min value is from]",
            "timestampCurrent": "[long, time last value was recorded]",
            "timestampMax": "[long, time max value was recorded]",
            "timestampMin": "[long, time min value was recorded]",
            "valueCurrent": "last value",
            "valueMax": "max value",
            "valueMin": "min value"
        }
    ]
}

---

Get Others

GET /api/rest/v2/experiment/log-other?experimentKey=KEY

Get an experiment's others (logged with log-other) summary.

Example Response

{
    "values": [
        {
            "name": "someName",
            "runContextCurrent": "run context of last value",
            "runContextMax": "run context of max value",
            "runContextMin": "run context of min value",
            "stepCurrent": "[long, step current value is from]",
            "stepMax": "[long, step max value is from]",
            "stepMin": "[long, step min value is from]",
            "timestampCurrent": "[long, time last value was recorded]",
            "timestampMax": "[long, time max value was recorded]",
            "timestampMin": "[long, time min value was recorded]",
            "valueCurrent": "last value",
            "valueMax": "max value",
            "valueMin": "min value"
        }
    ]
}

---

Get Tags

GET /api/rest/v2/experiment/tags?experimentKey=KEY

Get an experiment's tags.

Example Response

{
    "tags": [
        "a tag",
        "another tag"
    ]
}

---

Get System Details

GET /api/rest/v2/experiment/system-details?experimentKey=KEY

Get an experiment's system details.

Example Response

{
    "command": [
        "myScript.py",
        "-arg",
        "theArgument"
    ],
    "executable": "/usr/local/bin/python",
    "experimentKey": "KEY",
    "gpuStaticInfoList": [
        {
            "gpuIndex": "[Integer, index]",
            "name": "name",
            "powerLimit": "[Integer, max power used????]",
            "totalMemory": "[Integer, total memory used???]",
            "uuid": "someUniqueId"
        }
    ],
    "hostname": "hostname",
    "installedPackages": [
        "package",
        "anotherPackage"
    ],
    "ip": "ip address",
    "logAdditionalSystemInfoList": [
        {
            "key": "someKey",
            "value": "someValue"
        }
    ],
    "maxTotalMemory": "[double, max memory used]",
    "networkInterfaceIps": [
        "ip",
        "anotherIp"
    ],
    "os": "os with version info",
    "osPackages": [
        "package",
        "anotherPackage"
    ],
    "osType": "os experiment ran on",
    "pid": "[Integer, pid]",
    "pythonVersion": "python version",
    "pythonVersionVerbose": "python version with verbose flag",
    "systemMetricNames": [
        "name",
        "anotherName"
    ],
    "user": "system username"
}

---

Get Asset List

GET /api/rest/v2/experiment/asset/list?experimentKey=KEY&type=all

Get an experiment's asset list.

Example Response

{
    "assets": [
        {
            "assetId": "someAssetId",
            "audio": "[Boolean, whether the asset is an audio file]",
            "canView": "[Boolean, whether the asset is viewable as an image]",
            "createdAt": "[Long, timestamp asset was created in DB]",
            "dir": "someDirectory",
            "fileName": "someFileName",
            "fileSize": "[Long, file size]",
            "histogram": "[Boolean, whether the asset is a histogram file]",
            "image": "[Boolean, whether the asset was stored as an image]",
            "link": "link to download asset file",
            "metadata": "Metadata associated with the asset",
            "runContext": "someRunContext",
            "step": "[Integer, step asset was logged during]",
            "type": "the type of asset"
        }
    ]
}

Note: allowed types: all, unknown, audio, video, image, histogram3d, histogram_combined_3d, confusion-matrix

---

Get Asset

GET /api/rest/v2/experiment/asset/get-asset?experimentKey=KEY&assetId=someAssetId

Get an asset.

Example Response

"[Raw binary stream of asset or JSON {'msg':'no patch for experiment','code':200,'data':null,'sdk_error_code':0}]"

---

Get Experiment Model List

GET /api/rest/v2/experiment/model?experimentKey=KEY

Get the list of models created by a given experiment.

Example Response

{
    "models": [
        {
            "experimentKey": "KEY",
            "experimentModelId": "someExperimentModelId",
            "modelName": "someExperimentModelName"
        }
    ]
}

---

Get Experiment Model Asset List

GET /api/rest/v2/experiment/model/asset/list?experimentKey=KEY&modelName=myExperimentModelName

Get the list of assets for a particular experiment model.

Example Response

{
    "assets": [
        {
            "assetId": "someAssetId",
            "audio": "[Boolean, whether the asset is an audio file]",
            "canView": "[Boolean, whether the asset is viewable as an image]",
            "createdAt": "[Long, timestamp asset was created in DB]",
            "dir": "someDirectory",
            "fileName": "someFileName",
            "fileSize": "[Long, file size]",
            "histogram": "[Boolean, whether the asset is a histogram file]",
            "image": "[Boolean, whether the asset was stored as an image]",
            "link": "link to download asset file",
            "metadata": "Metadata associated with the asset",
            "runContext": "someRunContext",
            "step": "[Integer, step asset was logged during]",
            "type": "the type of asset"
        }
    ]
}

---

Download Experiment Model

GET /api/rest/v2/experiment/model/download?experimentKey=KEY&modelName=myExperimentModelName

Download a zip file of an experiment model.

Example Response

"[Raw stream of zip file as octet-stream]"

---

Get Store

GET /api/rest/v2/viz-instance/store/get?instanceId=INSTANCE_ID&projectId=PROJECT_ID

Get an entire store.

Example Response

"{'store': '{key1: value1, ...}'}"

---

Get Account Details

GET /api/rest/v2/account-details

Get account details from authenticated user's apiKey in header

Example Response

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

---