REST API

The MLflow REST API allows you to create, list, and get experiments and runs, and log params, metrics, and artifacts.

Table of Contents

Create Experiment
List Experiments
Get Experiment
Create Run
Get Run
Log Metric
Log Parameter
Get Metric
Get Metrics History
Search Runs
List Artifacts
Get Artifacts
Update 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.

Request Structure

Field Name	Type	Description
name	`STRING`	Experiment name. This field is required.

Response Structure

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

List Experiments

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

Return a list of all experiments.

Response Structure

Field Name	Type	Description
experiments	An array of Experiment	All experiments

Get Experiment

Get metadata for an experiment and a list of runs for the experiment.

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

Get experiment details.

Request Structure

Field Name	Type	Description
experiment_id	`INT64`	Identifier to get an experiment. This field is required.

Response Structure

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

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`	Unique identifier for the associated experiment.
user_id	`STRING`	User ID or LDAP for the user executing the run.
run_name	`STRING`	Human readable name for a run.
source_type	SourceType	Originating source for this run. One of `Notebook`, `Job`, `Project`, `Local` or `Unknown`.
source_name	`STRING`	String descriptor for source. For example, name or description of the notebook, or job name.
status	`RunStatus`	Current status of the run. One of `RUNNING`, `SCHEDULE`, `FINISHED`, `FAILED`, `KILLED`.
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 version of the source code used to create 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 will be chosen by default.
entry_point_name	`STRING`	Name of the entry point for the run.
run_tags	An array of RunTag	Additional metadata for run in key-value pairs.

Response Structure

Field Name	Type	Description
run_info	RunInfo	Metadata of the newly created run.

Get Run

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

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

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	Run UUID. This field is required.

Response Structure

Field Name	Type	Description
run	Run	Run details.

Log Metric

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

Log a metric for a run. Metrics key-value pair that record a single float measure. During a single execution of a run, a particular metric can be logged several times. Backend keeps track of historical values along with timestamps.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	Unique ID for the run for which metric is recorded.
key	`STRING`	Name of the metric.
value	`FLOAT`	Float value for the metric being logged.
timestamp	`INT64`	Unix timestamp in milliseconds at the time metric was logged.

Log Parameter

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

Log a parameter used for this run. Examples are params and hyperparameters used for ML training, or constant dates and values used in an ETL pipeline. A params is a STRING key-value pair. For a run, a single parameter is allowed to be logged only once.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	Unique ID for the run for which parameter is recorded.
key	`STRING`	Name of the parameter.
value	`STRING`	String value of the parameter.

Get Metric

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

Retrieve the logged value for a metric during a run. For a run, if this metric is logged more than once, this API retrieves only the latest value logged.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	Unique ID for the run for which metric is recorded.
metric_key	`STRING`	Name of the metric.

Response Structure

Field Name	Type	Description
metric	Metric	Latest reported metric.

Get Metrics History

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

Retrieve all logged values for a metric.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	Unique ID for the run for which metric is recorded.
key	`STRING`	Name of the metric.

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`	`GET`

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`	Identifier to get an experiment.
anded_expressions	An array of SearchExpression	Expressions describing runs.

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.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	Run UUID.
path	`STRING`	The relative_path to the output base directory.

Response Structure

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

Get Artifacts

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

List artifacts.

Request Structure

Field Name	Type	Description
run_uuid	`STRING`	Run UUID.
path	`STRING`	Relative path from root artifact location.

Update Run

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

Request Structure

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

Data Structures

Experiment

Field Name	Type	Description
experiment_id	`INT64`	Unique identifier for the experiment.
name	`STRING`	Human readable name that identifies this experiment.
artifact_location	`STRING`	Location where artifacts for this experiment are stored.

Metric

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

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

Run

Field Name	Type	Description
info	RunInfo
data	RunData

RunInfo

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 of the code used for the run.
entry_point_name	`STRING`	Name of the entry point for the run.
tags	An array of RunTag	Additional metadata key-value pairs.
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.

RunStatus

Status of a run

Status	Description
RUNNING	Run has been initiated.
SCHEDULED	Scheduled to run at a later time.
FINISHED	Run has completed.
FAILED	Execution failed.
KILLED	Was killed by user.

SourceType

Originating source for a run.

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

RunTag

Tag for a run

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

RunData

Field Name	Type	Description
metrics	An array of Metric	Metrics
params	An array of Param	Params

Param

Parameters associated with a run: key-value pair of strings.

Field Name	Type	Description
key	`STRING`	Key identifying this parameter.
value	`STRING`	Value for this parameter.

FileInfo

Field Name	Type	Description
path	`STRING`	The relative path to the `root_output_uri` for the run.
is_dir	`BOOL`	Whether the file is a directory.
file_size	`INT64`	File size in bytes. Unset for directories.

SearchExpression

Field Name	Type	Description
`metric` OR `parameter`	MetricSearchExpression OR ParameterSearchExpression	`AND` ed list of search expressions.

MetricSearchExpression

Field Name	Type	Description
float	Float Clause	Float clause for comparison.
key	`STRING`	Metric key for search.

ParameterSearchExpression

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

StringClause

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

Float Clause

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