Experiment

View as Markdown

An experiment and its metadata.

Experiment object

An experiment and its metadata.

experiment_idstring: Unique identifier for the experiment.

namestring: Human readable name that identifies the experiment.

artifact_locationstring: Location where artifacts for the experiment are stored.

lifecycle_stagestring: Current life cycle stage of the experiment: "active" or "deleted". Deleted experiments are not returned by APIs.

last_update_timeint64: Last update time

creation_timeint64: Creation time

tagsarray of object

Tags: Additional metadata key-value pairs.

Show child attributesHide child attributes

keystring: The tag key.

valuestring: The tag value.

View as Markdown

The Experiment object

{
  "experiment_id": "string",
  "name": "string",
  "artifact_location": "string",
  "lifecycle_stage": "string",
  "last_update_time": 0,
  "creation_time": 0,
  "tags": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

Get GA

GET /api/2.0/mlflow/experiments/get

Gets metadata for an experiment. This method works on deleted experiments.

API scopes: mlflow

Parameters

experiment_idstringquery: ID of the associated experiment.

Response

experimentobject

Experiment details.

Show child attributesHide child attributes

experiment_idstring: Unique identifier for the experiment.

namestring: Human readable name that identifies the experiment.

artifact_locationstring: Location where artifacts for the experiment are stored.

lifecycle_stagestring: Current life cycle stage of the experiment: "active" or "deleted". Deleted experiments are not returned by APIs.

last_update_timeint64: Last update time

creation_timeint64: Creation time

tagsarray of object

Tags: Additional metadata key-value pairs.

Show child attributesHide child attributes

keystring: The tag key.

valuestring: The tag value.

runsarray of object

A collection of active runs in the experiment. Note: this may not contain all of the experiment's active runs.

This field is deprecated. Please use the "Search Runs" API to fetch runs within an experiment.

Show child attributesHide child attributes

run_idstring: Unique identifier for the run.

run_uuidstring: [Deprecated, use run_id instead] Unique identifier for the run. This field will be removed in a future MLflow version.

experiment_idstring: The experiment ID.

run_namestring: The name of the run.

user_idstring: User who initiated the run. This field is deprecated as of MLflow 1.0, and will be removed in a future MLflow release. Use 'mlflow.user' tag instead.

statusstring: Current status of the run.
Values: RUNNING, SCHEDULED, FINISHED, FAILED, KILLED

start_timeint64: Unix timestamp of when the run started in milliseconds.

end_timeint64: Unix timestamp of when the run ended in milliseconds.

artifact_uristring: URI of the directory where artifacts should be uploaded. This can be a local path (starting with "/"), or a distributed file system (DFS) path, like s3://bucket/directory or dbfs:/my/directory. If not set, the local ./mlruns directory is chosen.

lifecycle_stagestring: Current life cycle stage of the experiment : OneOf("active", "deleted")

View as Markdown

Response

{
  "experiment": {
    "experiment_id": "string",
    "name": "string",
    "artifact_location": "string",
    "lifecycle_stage": "string",
    "last_update_time": 0,
    "creation_time": 0,
    "tags": [
      {}
    ]
  },
  "runs": [
    {
      "run_id": "string",
      "run_uuid": "string",
      "experiment_id": "string",
      "run_name": "string",
      "user_id": "string",
      "status": "string",
      "start_time": 0,
      "end_time": 0,
      "artifact_uri": "string",
      "lifecycle_stage": "string"
    }
  ]
}

List GA

GET /api/2.0/mlflow/experiments/list

Gets a list of all experiments.

API scopes: mlflow

Parameters

view_typestringquery: Qualifier for type of experiments to be returned. If unspecified, return only active experiments.
Values: ACTIVE_ONLY, DELETED_ONLY, ALL

max_resultsint64query: Maximum number of experiments desired. If max_results is unspecified, return all experiments. If max_results is too large, it'll be automatically capped at 1000. Callers of this endpoint are encouraged to pass max_results explicitly and leverage page_token to iterate through experiments.
Constraints: <= 1000

page_tokenstringquery: Token indicating the page of experiments to fetch

Response

Returns a list of Experiment objects.

View as Markdown

Response

{
  "experiments": [
    {
      "experiment_id": "string",
      "name": "string",
      "artifact_location": "string",
      "lifecycle_stage": "string",
      "last_update_time": 0,
      "creation_time": 0,
      "tags": [
        {}
      ]
    }
  ],
  "next_page_token": "string"
}

Create GA

POST /api/2.0/mlflow/experiments/create

Creates an experiment with a name. Returns the ID of the newly created experiment. Validates that another experiment with the same name does not already exist and fails if another experiment with the same name already exists.

Throws RESOURCE_ALREADY_EXISTS if an experiment with the given name exists. Note: In some contexts, this error may be remapped to ALREADY_EXISTS. To be safe, clients should check for both error codes.

API scopes: mlflow

Request body

namestring: Experiment name.

artifact_locationstring: Location where all artifacts for the experiment are stored. If not provided, the remote server will select an appropriate default.

tagsarray of object

A collection of tags to set on the experiment. Maximum tag size and number of tags per request depends on the storage backend. All storage backends are guaranteed to support tag keys up to 250 bytes in size and tag values up to 5000 bytes in size. All storage backends are also guaranteed to support up to 20 tags per request.

Show child attributesHide child attributes

keystring: The tag key.

valuestring: The tag value.

Response

experiment_idstring: Unique identifier for the experiment.

Update GA

POST /api/2.0/mlflow/experiments/update

Updates experiment metadata.

API scopes: mlflow

Request body

experiment_idstring: ID of the associated experiment.

new_namestring: If provided, the experiment's name is changed to the new name. The new name must be unique.

Delete GA

POST /api/2.0/mlflow/experiments/delete

Marks an experiment and associated metadata, runs, metrics, params, and tags for deletion. If the experiment uses FileStore, artifacts associated with the experiment are also deleted.

API scopes: mlflow

Request body

experiment_idstring: ID of the associated experiment.

Get Experiment By Name GA

GET /api/2.0/mlflow/experiments/get-by-name

Gets metadata for an experiment.

This endpoint will return deleted experiments, but prefers the active experiment if an active and deleted experiment share the same name. If multiple deleted experiments share the same name, the API will return one of them.

Throws RESOURCE_DOES_NOT_EXIST if no experiment with the specified name exists.

API scopes: mlflow

Parameters

experiment_namestringquery: Name of the associated experiment.

Response

experimentobject

Experiment details.

Show child attributesHide child attributes

experiment_idstring: Unique identifier for the experiment.

namestring: Human readable name that identifies the experiment.

artifact_locationstring: Location where artifacts for the experiment are stored.

lifecycle_stagestring: Current life cycle stage of the experiment: "active" or "deleted". Deleted experiments are not returned by APIs.

last_update_timeint64: Last update time

creation_timeint64: Creation time

tagsarray of object

Tags: Additional metadata key-value pairs.

Show child attributesHide child attributes

keystring: The tag key.

valuestring: The tag value.

View as Markdown

Response

{
  "experiment": {
    "experiment_id": "string",
    "name": "string",
    "artifact_location": "string",
    "lifecycle_stage": "string",
    "last_update_time": 0,
    "creation_time": 0,
    "tags": [
      {}
    ]
  }
}

Search Experiments GA

POST /api/2.0/mlflow/experiments/search

Searches for experiments that satisfy specified search criteria.

API scopes: mlflow

Request body

max_resultsint64: Maximum number of experiments desired. Max threshold is 3000.

page_tokenstring: Token indicating the page of experiments to fetch

filterstring: String representing a SQL filter condition (e.g. "name ILIKE 'my-experiment%'")

order_byarray of string: List of columns for ordering search results, which can include experiment name and last updated timestamp with an optional "DESC" or "ASC" annotation, where "ASC" is the default. Tiebreaks are done by experiment id DESC.

view_typestring: Qualifier for type of experiments to be returned. If unspecified, return only active experiments.
Values: ACTIVE_ONLY, DELETED_ONLY, ALL

Response

Returns a list of Experiment objects.

View as Markdown

Request

{
  "max_results": 0,
  "page_token": "string",
  "filter": "string",
  "order_by": [
    "string"
  ],
  "view_type": "string"
}

Response

{
  "experiments": [
    {
      "experiment_id": "string",
      "name": "string",
      "artifact_location": "string",
      "lifecycle_stage": "string",
      "last_update_time": 0,
      "creation_time": 0,
      "tags": [
        {}
      ]
    }
  ],
  "next_page_token": "string"
}

Set Experiment Tag GA

POST /api/2.0/mlflow/experiments/set-experiment-tag

Sets a tag on an experiment. Experiment tags are metadata that can be updated.

API scopes: mlflow

Request body

experiment_idstring: ID of the experiment under which to log the tag. Must be provided.

keystring: Name of the tag. Keys up to 250 bytes in size are supported.

valuestring: String value of the tag being logged. Values up to 64KB in size are supported.

Restore Experiment GA

POST /api/2.0/mlflow/experiments/restore

Restore an experiment marked for deletion. This also restores associated metadata, runs, metrics, params, and tags. If experiment uses FileStore, underlying artifacts associated with experiment are also restored.

Throws RESOURCE_DOES_NOT_EXIST if experiment was never created or was permanently deleted.

API scopes: mlflow

Request body

experiment_idstring: ID of the associated experiment.

Experiment object​

Get GA​

Parameters​

Response​

List GA​

Parameters​

Response​

Create GA​

Request body​

Response​

Update GA​

Request body​

Delete GA​

Request body​

Get Experiment By Name GA​

Parameters​

Response​

Search Experiments GA​

Request body​

Response​

Set Experiment Tag GA​

Request body​

Restore Experiment GA​

Request body​

Experiment object

Get GA

Parameters

Response

List GA

Parameters

Response

Create GA

Request body

Response

Update GA

Request body

Delete GA

Request body

Get Experiment By Name GA

Parameters

Response

Search Experiments GA

Request body

Response

Set Experiment Tag GA

Request body

Restore Experiment GA

Request body