Skip to main content

Experiment

View as Markdown

Experiment object​

An experiment and its metadata.

experiment_idstring

Unique identifier for the experiment.

namestring

Name of the experiment. A workspace experiment is named by its absolute path in the workspace; a notebook experiment has the path of its notebook.

artifact_locationstring

URI of the location where the artifacts of the experiment's runs are stored. Experiments created without an explicit location use MLflow-managed storage under dbfs:/databricks/mlflow-tracking/<experiment_id>.

lifecycle_stagestring

Current life cycle stage of the experiment: active or deleted. Deleted experiments are excluded from list and search results unless view_type requests them, and can be restored until they are permanently deleted.

last_update_timeint64

Time when the experiment metadata was last updated, as a Unix timestamp in milliseconds.

creation_timeint64

Time when the experiment was created, as a Unix timestamp in milliseconds.

tagsarray of object

Tags set on the experiment, as key-value pairs, including system tags such as mlflow.ownerId that MLflow maintains.

Show child attributesHide child attributes
keystring

The tag key. Keys are at most 255 characters long.

valuestring

The tag value. Values are at most 65535 characters long.

Get an experiment GA​

GET /api/2.0/mlflow/experiments/get

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

API scopes: mlflow

Parameters​

experiment_idstringRequiredquery

ID of the associated experiment.

Response​

experimentobject

Experiment details.

Show child attributesHide child attributes
experiment_idstring

Unique identifier for the experiment.

namestring

Name of the experiment. A workspace experiment is named by its absolute path in the workspace; a notebook experiment has the path of its notebook.

artifact_locationstring

URI of the location where the artifacts of the experiment's runs are stored. Experiments created without an explicit location use MLflow-managed storage under dbfs:/databricks/mlflow-tracking/<experiment_id>.

lifecycle_stagestring

Current life cycle stage of the experiment: active or deleted. Deleted experiments are excluded from list and search results unless view_type requests them, and can be restored until they are permanently deleted.

last_update_timeint64

Time when the experiment metadata was last updated, as a Unix timestamp in milliseconds.

creation_timeint64

Time when the experiment was created, as a Unix timestamp in milliseconds.

tagsarray of object

Tags set on the experiment, as key-value pairs, including system tags such as mlflow.ownerId that MLflow maintains.

Show child attributesHide child attributes
keystring

The tag key. Keys are at most 255 characters long.

valuestring

The tag value. Values are at most 65535 characters long.

runsarray of objectDeprecated

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_uuidstringDeprecated

[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_idstringDeprecated

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")

List experiments GA​

GET /api/2.0/mlflow/experiments/list

Gets a list of all experiments, ordered by creation time with the newest first.

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_resultsint64<= 1000query

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.

page_tokenstringquery

Page token returned as next_page_token by a previous call. Omit it to fetch the first page.

Response​

Returns a list of Experiment objects.

Create experiment GA​

POST /api/2.0/mlflow/experiments/create

1 more path

POST /api/2.0/preview/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​

namestringRequired

Name of the experiment, as an absolute path in the workspace. Experiments cannot be created under /Repos.

Example: /Users/jane.doe@example.com/churn-prediction

artifact_locationstring

URI of the location where the artifacts of the experiment's runs are stored, such as a Unity Catalog volume path of the form dbfs:/Volumes/<catalog>/<schema>/<volume>/<path>. The URI must have a scheme other than file and must not point under the MLflow-managed prefix dbfs:/databricks/mlflow-tracking. If omitted, artifacts are stored in MLflow-managed storage. See https://docs.databricks.com/aws/en/mlflow/experiments for the supported locations.

tagsarray of object

Tags to set on the new experiment, as key-value pairs. A request can include at most 100 tags.

Show child attributesHide child attributes
keystring

The tag key. Keys are at most 255 characters long.

valuestring

The tag value. Values are at most 65535 characters long.

Response​

experiment_idstring

Unique identifier for the experiment.

Update an experiment GA​

POST /api/2.0/mlflow/experiments/update

1 more path

POST /api/2.0/preview/mlflow/experiments/update

Updates experiment metadata. Only workspace experiments can be updated; a notebook experiment takes its name from its notebook.

API scopes: mlflow

Request body​

experiment_idstringRequired

ID of the associated experiment.

new_namestring

New name for the experiment, as an absolute path in the workspace. The new name must be unique.

Delete an experiment GA​

POST /api/2.0/mlflow/experiments/delete

1 more path

POST /api/2.0/preview/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. Only workspace experiments can be deleted through this method.

API scopes: mlflow

Request body​

experiment_idstringRequired

ID of the associated experiment.

Get an 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_namestringRequiredquery

Name of the associated experiment.

Response​

experimentobject

Experiment details.

Show child attributesHide child attributes
experiment_idstring

Unique identifier for the experiment.

namestring

Name of the experiment. A workspace experiment is named by its absolute path in the workspace; a notebook experiment has the path of its notebook.

artifact_locationstring

URI of the location where the artifacts of the experiment's runs are stored. Experiments created without an explicit location use MLflow-managed storage under dbfs:/databricks/mlflow-tracking/<experiment_id>.

lifecycle_stagestring

Current life cycle stage of the experiment: active or deleted. Deleted experiments are excluded from list and search results unless view_type requests them, and can be restored until they are permanently deleted.

last_update_timeint64

Time when the experiment metadata was last updated, as a Unix timestamp in milliseconds.

creation_timeint64

Time when the experiment was created, as a Unix timestamp in milliseconds.

tagsarray of object

Tags set on the experiment, as key-value pairs, including system tags such as mlflow.ownerId that MLflow maintains.

Show child attributesHide child attributes
keystring

The tag key. Keys are at most 255 characters long.

valuestring

The tag value. Values are at most 65535 characters long.

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 to return per page. Larger values are capped by the server, so use page_token to retrieve further pages.

page_tokenstring

Page token returned as next_page_token by a previous call. Omit it to fetch the first page.

filterstring

Filter condition on the experiment name and tags. The name attribute and tags.<key> support the operators =, !=, LIKE and ILIKE (case-insensitive LIKE), string values are wrapped in single quotes, and several conditions can be combined with AND. No wildcard is added automatically, so include % in a LIKE pattern where you need one.

Example: name ILIKE '/Users/jane.doe@example.com/%' AND tags.team = 'growth'

order_byarray of string

Columns to order the results by, each given as name, basename (the last segment of the name), experiment_id, creation_time or last_update_time with an optional ASC or DESC suffix, where ASC is the default. If omitted, results are ordered by last update time with the most recently updated experiment first. Tiebreaks are done by experiment id DESC.

Example: last_update_time 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.

Set a tag for an experiment GA​

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

1 more path

POST /api/2.0/preview/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_idstringRequired

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

keystringRequired

Key of the tag. Keys are at most 255 characters long. Setting a key that already exists replaces its value. System tags such as mlflow.ownerId, mlflow.ownerEmail and mlflow.experimentType cannot be set.

valuestringRequired

Value of the tag. Values are at most 65535 characters long.

Restore an experiment GA​

POST /api/2.0/mlflow/experiments/restore

1 more path

POST /api/2.0/preview/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.

Only workspace experiments can be restored through this method.

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

API scopes: mlflow

Request body​

experiment_idstringRequired

ID of the associated experiment.