REST API
The MLflow REST API allows you to create, list, and get experiments and runs, and log parameters, 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
.
MLflow also provides a health check endpoint at the /health
route, which responds with a 200 response code and
OK
in the response body.
Table of Contents
Create Experiment
Endpoint |
HTTP Method |
---|---|
|
|
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.
List Experiments
Endpoint |
HTTP Method |
---|---|
|
|
Get a list of all experiments.
Get Experiment
Endpoint |
HTTP Method |
---|---|
|
|
Get metadata for an experiment. This method works on deleted experiments.
Request Structure
Field Name |
Type |
Description |
---|---|---|
experiment_id |
|
ID of the associated experiment. This field is required. |
Response Structure
Field Name |
Type |
Description |
---|---|---|
experiment |
Experiment details. |
|
runs |
An array of RunInfo |
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. |
Get Experiment By Name
Endpoint |
HTTP Method |
---|---|
|
|
Get 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.
Delete Experiment
Endpoint |
HTTP Method |
---|---|
|
|
Mark an experiment and associated metadata, runs, metrics, params, and tags for deletion. If the experiment uses FileStore, artifacts associated with experiment are also deleted.
Restore Experiment
Endpoint |
HTTP Method |
---|---|
|
|
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.
Update Experiment
Endpoint |
HTTP Method |
---|---|
|
|
Update experiment metadata.
Create Run
Endpoint |
HTTP Method |
---|---|
|
|
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 |
|
ID of the associated experiment. |
user_id |
|
ID of the user executing 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. |
start_time |
|
Unix timestamp in milliseconds of when the run started. |
tags |
An array of RunTag |
Additional metadata for run. |
Get Run
Endpoint |
HTTP Method |
---|---|
|
|
Get metadata, metrics, params, and tags for a run. In the case where multiple metrics with the same key are logged for a run, return only the value with the latest timestamp. If there are multiple values with the latest timestamp, return the maximum of these values.
Request Structure
Field Name |
Type |
Description |
---|---|---|
run_id |
|
ID of the run to fetch. Must be provided. |
run_uuid |
|
[Deprecated, use run_id instead] ID of the run to fetch. This field will be removed in a future MLflow version. |
Log Metric
Endpoint |
HTTP Method |
---|---|
|
|
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_id |
|
ID of the run under which to log the metric. Must be provided. |
run_uuid |
|
[Deprecated, use run_id instead] ID of the run under which to log the metric. This field will be removed in a future MLflow version. |
key |
|
Name of the metric. This field is required. |
value |
|
Double value of the metric being logged. This field is required. |
timestamp |
|
Unix timestamp in milliseconds at the time metric was logged. This field is required. |
step |
|
Step at which to log the metric |
Log Batch
Endpoint |
HTTP Method |
---|---|
|
|
Log a batch of metrics, params, and tags for a run. If any data failed to be persisted, the server will respond with an error (non-200 status code). In case of error (due to internal server error or an invalid request), partial data may be written.
You can write metrics, params, and tags in interleaving fashion, but within a given entity type are guaranteed to follow the order specified in the request body. That is, for an API request like
{
"run_id": "2a14ed5c6a87499199e0106c3501eab8",
"metrics": [
{"key": "mae", "value": 2.5, "timestamp": 1552550804},
{"key": "rmse", "value": 2.7, "timestamp": 1552550804},
],
"params": [
{"key": "model_class", "value": "LogisticRegression"},
]
}
the server is guaranteed to write metric “rmse” after “mae”, though it may write param “model_class” before both metrics, after “mae”, or after both metrics.
The overwrite behavior for metrics, params, and tags is as follows:
Metrics: metric values are never overwritten. Logging a metric (key, value, timestamp) appends to the set of values for the metric with the provided key.
Tags: tag values can be overwritten by successive writes to the same tag key. That is, if multiple tag values with the same key are provided in the same API request, the last-provided tag value is written. Logging the same tag (key, value) is permitted - that is, logging a tag is idempotent.
Params: once written, param values cannot be changed (attempting to overwrite a param value will result in an error). However, logging the same param (key, value) is permitted - that is, logging a param is idempotent.
Request Limits
A single JSON-serialized API request may be up to 1 MB in size and contain:
No more than 1000 metrics, params, and tags in total
Up to 1000 metrics
Up to 100 params
Up to 100 tags
For example, a valid request might contain 900 metrics, 50 params, and 50 tags, but logging 900 metrics, 50 params, and 51 tags is invalid. The following limits also apply to metric, param, and tag keys and values:
Metric, param, and tag keys can be up to 250 characters in length
Param and tag values can be up to 250 characters in length
Request Structure
Field Name |
Type |
Description |
---|---|---|
run_id |
|
ID of the run to log under |
metrics |
An array of Metric |
Metrics to log. A single request can contain up to 1000 metrics, and up to 1000 metrics, params, and tags in total. |
params |
An array of Param |
Params to log. A single request can contain up to 100 params, and up to 1000 metrics, params, and tags in total. |
tags |
An array of RunTag |
Tags to log. A single request can contain up to 100 tags, and up to 1000 metrics, params, and tags in total. |
Set Experiment Tag
Endpoint |
HTTP Method |
---|---|
|
|
Set a tag on an experiment. Experiment tags are metadata that can be updated.
Request Structure
Field Name |
Type |
Description |
---|---|---|
experiment_id |
|
ID of the experiment under which to log the tag. Must be provided. This field is required. |
key |
|
Name of the tag. Maximum size depends on storage backend. All storage backends are guaranteed to support key values up to 250 bytes in size. This field is required. |
value |
|
String value of the tag being logged. Maximum size depends on storage backend. All storage backends are guaranteed to support key values up to 5000 bytes in size. This field is required. |
Set Tag
Endpoint |
HTTP Method |
---|---|
|
|
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_id |
|
ID of the run under which to log the tag. Must be provided. |
run_uuid |
|
[Deprecated, use run_id instead] ID of the run under which to log the tag. This field will be removed in a future MLflow version. |
key |
|
Name of the tag. Maximum size depends on storage backend. All storage backends are guaranteed to support key values up to 250 bytes in size. This field is required. |
value |
|
String value of the tag being logged. Maximum size depends on storage backend. All storage backends are guaranteed to support key values up to 5000 bytes in size. This field is required. |
Delete Tag
Endpoint |
HTTP Method |
---|---|
|
|
Delete a tag on a run. Tags are run metadata that can be updated during a run and after a run completes.
Log Param
Endpoint |
HTTP Method |
---|---|
|
|
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_id |
|
ID of the run under which to log the param. Must be provided. |
run_uuid |
|
[Deprecated, use run_id instead] ID of the run under which to log the param. This field will be removed in a future MLflow version. |
key |
|
Name of the param. Maximum size is 255 bytes. This field is required. |
value |
|
String value of the param being logged. Maximum size is 500 bytes. This field is required. |
Get Metric History
Endpoint |
HTTP Method |
---|---|
|
|
Get a list of all values for the specified metric for a given run.
Request Structure
Field Name |
Type |
Description |
---|---|---|
run_id |
|
ID of the run from which to fetch metric values. Must be provided. |
run_uuid |
|
[Deprecated, use run_id instead] ID of the run from which to fetch metric values. This field will be removed in a future MLflow version. |
metric_key |
|
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 |
---|---|
|
|
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 |
List of experiment IDs to search over. |
filter |
|
A filter expression over params, metrics, and tags, that allows returning a subset of runs. The syntax is a subset of SQL that supports ANDing together binary operations between a param, metric, or tag and a constant. Example: You can select columns with special characters (hyphen, space, period, etc.) by using double quotes:
Supported operators are |
run_view_type |
Whether to display only active, only deleted, or all runs. Defaults to only active runs. |
|
max_results |
|
Maximum number of runs desired. Max threshold is 50000 |
order_by |
An array of |
List of columns to be ordered by, including attributes, params, metrics, and tags with an optional “DESC” or “ASC” annotation, where “ASC” is the default. Example: [“params.input DESC”, “metrics.alpha ASC”, “metrics.rmse”] Tiebreaks are done by start_time DESC followed by run_id for runs with the same start time (and this is the default ordering criterion if order_by is not provided). |
page_token |
|
Response Structure
Field Name |
Type |
Description |
---|---|---|
runs |
An array of Run |
Runs that match the search criteria. |
next_page_token |
|
List Artifacts
Endpoint |
HTTP Method |
---|---|
|
|
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_id |
|
ID of the run whose artifacts to list. Must be provided. |
run_uuid |
|
[Deprecated, use run_id instead] ID of the run whose artifacts to list. This field will be removed in a future MLflow version. |
path |
|
Filter artifacts matching this path (a relative path from the root artifact directory). |
Response Structure
Field Name |
Type |
Description |
---|---|---|
root_uri |
|
Root artifact directory for the run. |
files |
An array of FileInfo |
File location and metadata for artifacts. |
Update Run
Endpoint |
HTTP Method |
---|---|
|
|
Update run metadata.
Request Structure
Field Name |
Type |
Description |
---|---|---|
run_id |
|
ID of the run to update. Must be provided. |
run_uuid |
|
[Deprecated, use run_id instead] ID of the run to update.. This field will be removed in a future MLflow version. |
status |
Updated status of the run. |
|
end_time |
|
Unix timestamp in milliseconds of when the run ended. |
Create RegisteredModel
Endpoint |
HTTP Method |
---|---|
|
|
Note
Experimental: This API may change or be removed in a future release without warning.
Throws RESOURCE_ALREADY_EXISTS
if a registered model with the given name exists.
Get RegisteredModel Details
Endpoint |
HTTP Method |
---|---|
|
|
Note
Experimental: This API may change or be removed in a future release without warning.
Update RegisteredModel
Endpoint |
HTTP Method |
---|---|
|
|
Note
Experimental: This API may change or be removed in a future release without warning.
Delete RegisteredModel
Endpoint |
HTTP Method |
---|---|
|
|
Note
Experimental: This API may change or be removed in a future release without warning.
List RegisteredModels
Endpoint |
HTTP Method |
---|---|
|
|
Note
Experimental: This API may change or be removed in a future release without warning.
Response Structure
Field Name |
Type |
Description |
---|---|---|
registered_models_detailed |
An array of RegisteredModelDetailed |
Get Latest ModelVersions
Endpoint |
HTTP Method |
---|---|
|
|
Note
Experimental: This API may change or be removed in a future release without warning.
Request Structure
Field Name |
Type |
Description |
---|---|---|
registered_model |
Registered model. This field is required. |
|
stages |
An array of |
List of stages. |
Response Structure
Field Name |
Type |
Description |
---|---|---|
model_versions_detailed |
An array of ModelVersionDetailed |
Latest version models for each requests stage. Only return models with current |
Create ModelVersion
Endpoint |
HTTP Method |
---|---|
|
|
Note
Experimental: This API may change or be removed in a future release without warning.
Request Structure
Field Name |
Type |
Description |
---|---|---|
name |
|
Register model under this name This field is required. |
source |
|
URI indicating the location of the model artifacts. This field is required. |
run_id |
|
MLflow run ID for correlation, if |
Get ModelVersion Details
Endpoint |
HTTP Method |
---|---|
|
|
Note
Experimental: This API may change or be removed in a future release without warning.
Update ModelVersion
Endpoint |
HTTP Method |
---|---|
|
|
Note
Experimental: This API may change or be removed in a future release without warning.
Delete ModelVersion
Endpoint |
HTTP Method |
---|---|
|
|
Note
Experimental: This API may change or be removed in a future release without warning.
Search ModelVersions
Endpoint |
HTTP Method |
---|---|
|
|
Note
Experimental: This API may change or be removed in a future release without warning.
Request Structure
Field Name |
Type |
Description |
---|---|---|
filter |
|
String filter condition, like “name=’my-model-name’”. Must be a single boolean condition, with string values wrapped in single quotes. |
max_results |
|
Maximum number of models desired. Max threshold is 1000. |
order_by |
An array of |
List of columns to be ordered by including model name, version, stage with an optional “DESC” or “ASC” annotation, where “ASC” is the default. Tiebreaks are done by latest stage transition timestamp, followed by name ASC, followed by version DESC. |
page_token |
|
Pagination token to go to next page based on previous search query. |
Response Structure
Field Name |
Type |
Description |
---|---|---|
model_versions_detailed |
An array of ModelVersionDetailed |
Models that match the search criteria |
next_page_token |
|
Pagination token to request next page of models for the same search query. |
Get Download URI For ModelVersion Artifacts
Endpoint |
HTTP Method |
---|---|
|
|
Note
Experimental: This API may change or be removed in a future release without warning.
Data Structures
Experiment
Experiment
Field Name |
Type |
Description |
---|---|---|
experiment_id |
|
Unique identifier for the experiment. |
name |
|
Human readable name that identifies the experiment. |
artifact_location |
|
Location where artifacts for the experiment are stored. |
lifecycle_stage |
|
Current life cycle stage of the experiment: “active” or “deleted”. Deleted experiments are not returned by APIs. |
last_update_time |
|
Last update time |
creation_time |
|
Creation time |
tags |
An array of ExperimentTag |
Tags: Additional metadata key-value pairs. |
ExperimentTag
Tag for an experiment.
Field Name |
Type |
Description |
---|---|---|
key |
|
The tag key. |
value |
|
The tag value. |
FileInfo
Metadata of a single artifact file or directory.
Field Name |
Type |
Description |
---|---|---|
path |
|
Path relative to the root artifact directory run. |
is_dir |
|
Whether the path is a directory. |
file_size |
|
Size in bytes. Unset for directories. |
Metric
Metric associated with a run, represented as a key-value pair.
Field Name |
Type |
Description |
---|---|---|
key |
|
Key identifying this metric. |
value |
|
Value associated with this metric. |
timestamp |
|
The timestamp at which this metric was recorded. |
step |
|
Step at which to log the metric. |
ModelVersion
Note
Experimental: This entity may change or be removed in a future release without warning.
Field Name |
Type |
Description |
---|---|---|
registered_model |
Registered model. |
|
version |
|
Model’s version number. |
ModelVersionDetailed
Note
Experimental: This entity may change or be removed in a future release without warning.
Field Name |
Type |
Description |
---|---|---|
model_version |
Model Version |
|
creation_timestamp |
|
Timestamp recorded when this |
last_updated_timestamp |
|
Timestamp recorded when metadata for this |
user_id |
|
User that created this |
current_stage |
|
Current stage for this |
description |
|
Description of this |
source |
|
URI indicating the location of the source model artifacts, used when creating |
run_id |
|
MLflow run ID used when creating |
status |
Current status of |
|
status_message |
|
Details on current |
Param
Param associated with a run.
Field Name |
Type |
Description |
---|---|---|
key |
|
Key identifying this param. |
value |
|
Value associated with this param. |
RegisteredModel
Note
Experimental: This entity may change or be removed in a future release without warning.
Field Name |
Type |
Description |
---|---|---|
name |
|
Unique name for the model. |
RegisteredModelDetailed
Note
Experimental: This entity may change or be removed in a future release without warning.
Field Name |
Type |
Description |
---|---|---|
registered_model |
Registered model. |
|
creation_timestamp |
|
Timestamp recorded when this |
last_updated_timestamp |
|
Timestamp recorded when metadata for this |
user_id |
|
User that created this |
description |
|
Description of this |
latest_versions |
An array of ModelVersionDetailed |
Collection of latest model versions for each stage.
Only contains models with current |
RunData
Run data (metrics, params, and tags).
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_id |
|
Unique identifier for the run. |
run_uuid |
|
[Deprecated, use run_id instead] Unique identifier for the run. This field will be removed in a future MLflow version. |
experiment_id |
|
The experiment ID. |
user_id |
|
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. |
status |
Current status of the run. |
|
start_time |
|
Unix timestamp of when the run started in milliseconds. |
end_time |
|
Unix timestamp of when the run ended in milliseconds. |
artifact_uri |
|
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 |
lifecycle_stage |
|
Current life cycle stage of the experiment : OneOf(“active”, “deleted”) |
RunTag
Tag for a run.
Field Name |
Type |
Description |
---|---|---|
key |
|
The tag key. |
value |
|
The tag value. |
ModelVersionStatus
Note
Experimental: This entity may change or be removed in a future release without warning.
Name |
Description |
---|---|
PENDING_REGISTRATION |
Request to register a new model version is pending as server performs background tasks. |
FAILED_REGISTRATION |
Request to register a new model version has failed. |
READY |
Model version is ready for use. |
PENDING_DELETION |
Request to delete an existing model version is pending as server performs background tasks. |
FAILED_DELETION |
Request to delete an existing model version has failed. |