Experiment
An experiment and its metadata.
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:
activeordeleted. Deleted experiments are excluded from list and search results unlessview_typerequests 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.ownerIdthat 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
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:
activeordeleted. Deleted experiments are excluded from list and search results unlessview_typerequests 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.ownerIdthat 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.
RUNNINGSCHEDULEDFINISHEDFAILEDKILLED
- 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/directoryordbfs:/my/directory. If not set, the local./mlrunsdirectory is chosen.
- lifecycle_stagestring
Current life cycle stage of the experiment : OneOf("active", "deleted")
List experiments GA
GET
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.
ACTIVE_ONLYDELETED_ONLYALL
- max_resultsint64<= 1000query
Maximum number of experiments desired. If
max_resultsis unspecified, return all experiments. Ifmax_resultsis 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_tokenby a previous call. Omit it to fetch the first page.
Response
Returns a list of Experiment objects.
Create experiment GA
POST
1 more path
POST
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.
- 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 thanfileand must not point under the MLflow-managed prefixdbfs:/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
1 more path
POST
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
1 more path
POST
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
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:
activeordeleted. Deleted experiments are excluded from list and search results unlessview_typerequests 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.ownerIdthat 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
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_tokento retrieve further pages.
- page_tokenstring
Page token returned as
next_page_tokenby a previous call. Omit it to fetch the first page.
- filterstring
Filter condition on the experiment name and tags. The
nameattribute andtags.<key>support the operators=,!=,LIKEandILIKE(case-insensitiveLIKE), string values are wrapped in single quotes, and several conditions can be combined withAND. No wildcard is added automatically, so include%in aLIKEpattern where you need one.
- order_byarray of string
Columns to order the results by, each given as
name,basename(the last segment of the name),experiment_id,creation_timeorlast_update_timewith an optionalASCorDESCsuffix, whereASCis 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.
- view_typestring
Qualifier for type of experiments to be returned. If unspecified, return only active experiments.
ACTIVE_ONLYDELETED_ONLYALL
Response
Returns a list of Experiment objects.
Set a tag for an experiment GA
POST
1 more path
POST
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.ownerEmailandmlflow.experimentTypecannot be set.
- valuestringRequired
Value of the tag. Values are at most 65535 characters long.
Restore an experiment GA
POST
1 more path
POST
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.