REST API

The MLflow REST API allows you to create, list, and get experiments and runs, and log params, metrics, and artifacts. The API is hosted under the /api route on the MLflow tracking server. For example, to list experiments on a tracking server hosted at http://localhost:5000, access http://localhost:5000/api/2.0/preview/mlflow/experiments/list.

Table of Contents

Create Experiment
List Experiments
Get Experiment
Delete Experiment
Restore Experiment
Create Run
Get Run
Log Metric
Set Tag
Log Param
Get Param
Get Metric
Get Metric History
Search Runs
List Artifacts
Update Run
Delete Run
Restore Run
Data Structures

Create Experiment

Endpoint	HTTP Method
`2.0/preview/mlflow/experiments/create`	`POST`

Create 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 a experiment with the given name exists.

Request Structure

Field Name	Type	Description
name	`STRING`	Experiment name. This field is required.
artifact_location	`STRING`	Location where all artifacts for the experiment are stored. If not provided, the remote server will select an appropriate default.

Response Structure

Field Name	Type	Description
experiment_id	`INT64`	Unique identifier for the experiment.

List Experiments

Endpoint	HTTP Method
`2.0/preview/mlflow/experiments/list`	`GET`

Get a list of all experiments.

Request Structure

Field Name	Type	Description
view_type	ViewType	Qualifier for type of experiments to be returned. If unspecified, return only active experiments.

Response Structure

Field Name	Type	Description
experiments	An array of Experiment	All experiments

Get Experiment

Endpoint	HTTP Method
`2.0/preview/mlflow/experiments/get`	`GET`

Get metadata for an experiment and a list of runs for the experiment. This RPC will work on deleted experiments.

Request Structure

Field Name	Type	Description
experiment_id	`INT64`	ID of the associated experiment. This field is required.

Response Structure

Field Name	Type	Description
experiment	Experiment	Returns experiment details.
runs	An array of RunInfo	All (max limit to be imposed) active runs associated with this experiment.

Delete Experiment

Endpoint	HTTP Method
`2.0/preview/mlflow/experiments/delete`	`POST`

Mark an experiment and associated runs, params, metrics, … etc for deletion. If the experiment uses FileStore, artifacts associated with experiment are also deleted.

Request Structure

Field Name	Type	Description
experiment_id	`INT64`	ID of the associated experiment. This field is required.

Restore Experiment

Endpoint	HTTP Method
`2.0/preview/mlflow/experiments/restore`	`POST`

Restore an experiment marked for deletion. This also restores associated metadata, runs, metrics, and params. 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.

Request Structure

Field Name	Type	Description
experiment_id	`INT64`	ID of the associated experiment. This field is required.

Create Run

Endpoint	HTTP Method
`2.0/preview/mlflow/runs/create`	`POST`

Create a new run within an experiment. A run is usually a single execution of a machine learning or data ETL pipeline. MLflow uses runs to track Param, Metric, and RunTag associated with a single execution.

Request Structure

Field Name	Type	Description
experiment_id	`INT64`	ID of the associated experiment.
user_id	`STRING`	ID of the user executing the run.
run_name	`STRING`	Human readable name for the run.
source_type	SourceType	Originating source for the run.
source_name	`STRING`	String descriptor for the run’s source. For example, name or description of a notebook, or the URL or path to a project.
entry_point_name	`STRING`	Name of the project entry point associated with the current run, if any.
start_time	`INT64`	Unix timestamp of when the run started in milliseconds.
source_version	`STRING`	Git commit hash of the source code used to create run.
tags	An array of RunTag	Additional metadata for run.
parent_run_id	`STRING`	ID of the parent run which started this run.

Response Structure

Field Name	Type	Description
run	Run	The newly created run.

Get Run

Endpoint	HTTP Method
`2.0/preview/mlflow/runs/get`	`GET`

Get metadata, params, tags, and metrics for a run. Only the last logged value for each metric is returned.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	ID of the run to fetch. This field is required.

Response Structure

Field Name	Type	Description
run	Run	Run metadata (name, start time, etc) and data (metrics, params, etc).

Log Metric

Endpoint	HTTP Method
`2.0/preview/mlflow/runs/log-metric`	`POST`

Log a metric for a run. A metric is a key-value pair (string key, float value) with an associated timestamp. Examples include the various metrics that represent ML model accuracy. A metric can be logged multiple times.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	ID of the run under which to log the metric. This field is required.
key	`STRING`	Name of the metric. This field is required.
value	`DOUBLE`	Double value of the metric being logged. This field is required.
timestamp	`INT64`	Unix timestamp in milliseconds at the time metric was logged. This field is required.

Set Tag

Endpoint	HTTP Method
`2.0/preview/mlflow/runs/set-tag`	`POST`

Set a tag on a run. Tags are run metadata that can be updated during a run and after a run completes.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	ID of the run under which to set the tag. This field is required.
key	`STRING`	Name of the tag. Maximum size is 255 bytes. This field is required.
value	`STRING`	String value of the tag being logged. Maximum size is 5000 bytes. This field is required.

Log Param

Endpoint	HTTP Method
`2.0/preview/mlflow/runs/log-parameter`	`POST`

Log a param used for a run. A param is a key-value pair (string key, string value). Examples include hyperparameters used for ML model training and constant dates and values used in an ETL pipeline. A param can be logged only once for a run.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	ID of the run under which to log the param. This field is required.
key	`STRING`	Name of the param. Maximum size is 255 bytes. This field is required.
value	`STRING`	String value of the param being logged. Maximum size is 500 bytes. This field is required.

Get Param

Endpoint	HTTP Method
`2.0/preview/mlflow/params/get`	`GET`

Get a param value.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	ID of the run from which to retrieve the param value. This field is required.
param_name	`STRING`	Name of the param. This field is required.

Response Structure

Field Name	Type	Description
parameter	Param	Param key-value pair.

Get Metric

Endpoint	HTTP Method
`2.0/preview/mlflow/metrics/get`	`GET`

Get the value for a metric logged during a run. If the metric is logged more than once, returns the last logged value.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	ID of the run from which to retrieve the metric value. This field is required.
metric_key	`STRING`	Name of the metric. This field is required.

Response Structure

Field Name	Type	Description
metric	Metric	Latest reported value of the specified metric.

Get Metric History

Endpoint	HTTP Method
`2.0/preview/mlflow/metrics/get-history`	`GET`

Get a list of all values for the specified metric for a given run.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	ID of the run from which to fetch metric values. This field is required.
metric_key	`STRING`	Name of the metric. This field is required.

Response Structure

Field Name	Type	Description
metrics	An array of Metric	All logged values for this metric.

Search Runs

Endpoint	HTTP Method
`2.0/preview/mlflow/runs/search`	`POST`

Search for runs that satisfy expressions. Search expressions can use Metric and Param keys.

Request Structure

Field Name	Type	Description
experiment_ids	An array of `INT64`	List of experiment IDs to search over.
anded_expressions	An array of SearchExpression	Expressions describing runs (AND-ed together when filtering runs).
run_view_type	ViewType

Response Structure

Field Name	Type	Description
runs	An array of Run	Runs that match the search criteria.

List Artifacts

Endpoint	HTTP Method
`2.0/preview/mlflow/artifacts/list`	`GET`

List artifacts for a run. Takes an optional artifact_path prefix which if specified, the response contains only artifacts with the specified prefix.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	ID of the run whose artifacts to list.
path	`STRING`	Filter artifacts matching this path (a relative path from the root artifact directory).

Response Structure

Field Name	Type	Description
root_uri	`STRING`	Root artifact directory for the run.
files	An array of FileInfo	File location and metadata for artifacts.

Update Run

Endpoint	HTTP Method
`2.0/preview/mlflow/runs/update`	`POST`

Update run metadata.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	ID of the run to update. This field is required.
status	RunStatus	Updated status of the run.
end_time	`INT64`	Unix timestamp of when the run ended in milliseconds.

Response Structure

Field Name	Type	Description
run_info	RunInfo	Updated metadata of the run.

Delete Run

Endpoint	HTTP Method
`2.0/preview/mlflow/runs/delete`	`POST`

This operation will mark the run for deletion.

Request Structure

Field Name	Type	Description
run_id	`STRING`	This field is required.

Restore Run

Endpoint	HTTP Method
`2.0/preview/mlflow/runs/restore`	`POST`

Restore a deleted run.

Request Structure

Field Name	Type	Description
run_id	`STRING`	This field is required.

Data Structures

DoubleClause

Field Name	Type	Description
comparator	`STRING`	OneOf (“>”, “>=”, “==”, “!=”, “<=”, “<”)
value	`DOUBLE`	Float value for comparison.

Experiment

Field Name	Type	Description
experiment_id	`INT64`	Unique identifier for the experiment.
name	`STRING`	Human readable name that identifies the experiment.
artifact_location	`STRING`	Location where artifacts for the experiment are stored.
lifecycle_stage	`STRING`	Current life cycle stage of the experiment: “active” or “deleted”. Deleted experiments are not returned by APIs.
last_update_time	`INT64`	Last update time
creation_time	`INT64`	Creation time

FileInfo

Metadata of a single artifact file or directory.

Field Name	Type	Description
path	`STRING`	Path relative to the root artifact directory run.
is_dir	`BOOL`	Whether the path is a directory.
file_size	`INT64`	Size in bytes. Unset for directories.

FloatClause

Field Name	Type	Description
comparator	`STRING`	OneOf (“>”, “>=”, “==”, “!=”, “<=”, “<”)
value	`FLOAT`	Float value for comparison.

Metric

Metric associated with a run, represented as a key-value pair.

Field Name	Type	Description
key	`STRING`	Key identifying this metric.
value	`DOUBLE`	Value associated with this metric.
timestamp	`INT64`	The timestamp at which this metric was recorded.

MetricSearchExpression

Field Name Type Description

float OR double

FloatClause OR DoubleClause

If float, [Deprecated in 0.7.0, to be removed in future version] Float clause for comparison. Use ‘double’ instead.

If double, double clause of comparison

key STRING Metric key for search.

Param

Param associated with a run.

Field Name	Type	Description
key	`STRING`	Key identifying this param.
value	`STRING`	Value associated with this param.

ParameterSearchExpression

Field Name	Type	Description
`string`	StringClause	If `string`, string clause for comparison.
key	`STRING`	Param key for search.

Run

A single run.

Field Name	Type	Description
info	RunInfo	Run metadata.
data	RunData	Run data.

RunData

Run data (metrics, params, etc).

Field Name	Type	Description
metrics	An array of Metric	Run metrics.
params	An array of Param	Run parameters.
tags	An array of RunTag	Additional metadata key-value pairs.

RunInfo

Metadata of a single run.

Field Name	Type	Description
run_uuid	`STRING`	Unique identifier for the run.
experiment_id	`INT64`	The experiment ID.
name	`STRING`	Human readable name that identifies this run.
source_type	SourceType	Source type.
source_name	`STRING`	Source identifier: GitHub URL, name of notebook, name of job, etc.
user_id	`STRING`	User who initiated the run.
status	RunStatus	Current status of the run.
start_time	`INT64`	Unix timestamp of when the run started in milliseconds.
end_time	`INT64`	Unix timestamp of when the run ended in milliseconds.
source_version	`STRING`	Git commit hash of the code used for the run.
entry_point_name	`STRING`	Name of the entry point for the run.
artifact_uri	`STRING`	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_stage	`STRING`	Current life cycle stage of the experiment : OneOf(“active”, “deleted”)

RunTag

Tag for a run.

Field Name	Type	Description
key	`STRING`	The tag key.
value	`STRING`	The tag value.

SearchExpression

Field Name Type Description

metric OR parameter

MetricSearchExpression OR ParameterSearchExpression

If metric, a metric search expression.

If parameter, a parameter search expression.

StringClause

Field Name	Type	Description
comparator	`STRING`	OneOf (“==”, “!=”, “~”)
value	`STRING`	String value for comparison.

RunStatus

Status of a run.

Name	Description
RUNNING	Run has been initiated.
SCHEDULED	Run is scheduled to run at a later time.
FINISHED	Run has completed.
FAILED	Run execution failed.
KILLED	Run killed by user.

SourceType

Source that generated a run.

Name	Description
NOTEBOOK	Databricks notebook environment.
JOB	Scheduled or Run Now job.
PROJECT	As a prepackaged project: either a Docker image or GitHub source, etc.
LOCAL	Local run: Using CLI, IDE, or local notebook.
UNKNOWN	Unknown source type.

ViewType

View type for ListExperiments query.

Name	Description
ACTIVE_ONLY	Default. Return only active experiments.
DELETED_ONLY	Return only deleted experiments.
ALL	Get all experiments.