Run
A single run.
Run object
A single run.
- infoobject
Run metadata.
Show child attributesHide child attributes
- run_idstring
Unique identifier for the run.
- run_uuidstring
[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_idstring
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.
- 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")
- dataobject
Run data.
Show child attributesHide child attributes
- metricsarray of object
Run metrics.
Show child attributesHide child attributes
- keystring
The key identifying the metric.
- valuedouble
The value of the metric.
- timestampint64
The timestamp at which the metric was recorded.
- stepint64
The step at which the metric was logged.
- dataset_namestring
The name of the dataset associated with the metric. E.g. “my.uc.table@2” “nyc-taxi-dataset”, “fantastic-elk-3”
- dataset_digeststring
The dataset digest of the dataset associated with the metric, e.g. an md5 hash of the dataset that uniquely identifies it within datasets of the same name.
- model_idstring
The ID of the logged model or registered model version associated with the metric, if applicable.
- run_idstring
The ID of the run containing the metric.
- paramsarray of object
Run parameters.
Show child attributesHide child attributes
- keystring
Key identifying this param.
- valuestring
Value associated with this param.
- tagsarray of object
Additional metadata key-value pairs.
Show child attributesHide child attributes
- keystring
The tag key.
- valuestring
The tag value.
- inputsobject
Run inputs.
Show child attributesHide child attributes
- dataset_inputsarray of object
Run metrics.
Show child attributesHide child attributes
- tagsarray of object
A list of tags for the dataset input, e.g. a “context” tag with value “training”
Show child attributesHide child attributes
- keystring
The tag key.
- valuestring
The tag value.
- datasetobject
The dataset being used as a Run input.
Show child attributesHide child attributes
- namestring
The name of the dataset. E.g. “my.uc.table@2” “nyc-taxi-dataset”, “fantastic-elk-3”
- digeststring
Dataset digest, e.g. an md5 hash of the dataset that uniquely identifies it within datasets of the same name.
- source_typestring
The type of the dataset source, e.g. ‘databricks-uc-table’, ‘DBFS’, ‘S3’, ...
- sourcestring
Source information for the dataset. Note that the source may not exactly reproduce the dataset if it was transformed / modified before use with MLflow.
- schemastring
The schema of the dataset. E.g., MLflow ColSpec JSON for a dataframe, MLflow TensorSpec JSON for an ndarray, or another schema format.
- profilestring
The profile of the dataset. Summary statistics for the dataset, such as the number of rows in a table, the mean / std / mode of each column in a table, or the number of elements in an array.
- model_inputsarray of object
Model inputs to the Run.
Show child attributesHide child attributes
- model_idstring
The unique identifier of the model.
Get GA
GET
Gets the 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.
API scopes: mlflow
Parameters
- run_idstringquery
ID of the run to fetch. Must be provided.
- run_uuidstringquery
[Deprecated, use
run_idinstead] ID of the run to fetch. This field will be removed in a future MLflow version.
Response
- runobject
Run metadata (name, start time, etc) and data (metrics, params, and tags).
Show child attributesHide child attributes
- infoobject
Run metadata.
Show child attributesHide child attributes
- run_idstring
Unique identifier for the run.
- run_uuidstring
[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_idstring
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.
- 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")
- dataobject
Run data.
Show child attributesHide child attributes
- metricsarray of object
Run metrics.
Show child attributesHide child attributes
- keystring
The key identifying the metric.
- valuedouble
The value of the metric.
- timestampint64
The timestamp at which the metric was recorded.
- stepint64
The step at which the metric was logged.
- dataset_namestring
The name of the dataset associated with the metric. E.g. “my.uc.table@2” “nyc-taxi-dataset”, “fantastic-elk-3”
- dataset_digeststring
The dataset digest of the dataset associated with the metric, e.g. an md5 hash of the dataset that uniquely identifies it within datasets of the same name.
- model_idstring
The ID of the logged model or registered model version associated with the metric, if applicable.
- run_idstring
The ID of the run containing the metric.
- paramsarray of object
Run parameters.
Show child attributesHide child attributes
- keystring
Key identifying this param.
- valuestring
Value associated with this param.
- tagsarray of object
Additional metadata key-value pairs.
Show child attributesHide child attributes
- keystring
The tag key.
- valuestring
The tag value.
- inputsobject
Run inputs.
Show child attributesHide child attributes
- dataset_inputsarray of object
Run metrics.
Show child attributesHide child attributes
- tagsarray of object
A list of tags for the dataset input, e.g. a “context” tag with value “training”
- datasetobject
The dataset being used as a Run input.
- model_inputsarray of object
Model inputs to the Run.
Show child attributesHide child attributes
- model_idstring
The unique identifier of the model.
Create GA
POST
Creates 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 the mlflowParam,
mlflowMetric, and mlflowRunTag associated with a single execution.
API scopes: mlflow
Request body
- experiment_idstring
ID of the associated experiment.
- user_idstring
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.
- run_namestring
The name of the run.
- start_timeint64
Unix timestamp in milliseconds of when the run started.
- tagsarray of object
Additional metadata for run.
Show child attributesHide child attributes
- keystring
The tag key.
- valuestring
The tag value.
Response
- runobject
The newly created run.
Show child attributesHide child attributes
- infoobject
Run metadata.
Show child attributesHide child attributes
- run_idstring
Unique identifier for the run.
- run_uuidstring
[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_idstring
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.
- 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")
- dataobject
Run data.
Show child attributesHide child attributes
- metricsarray of object
Run metrics.
Show child attributesHide child attributes
- keystring
The key identifying the metric.
- valuedouble
The value of the metric.
- timestampint64
The timestamp at which the metric was recorded.
- stepint64
The step at which the metric was logged.
- dataset_namestring
The name of the dataset associated with the metric. E.g. “my.uc.table@2” “nyc-taxi-dataset”, “fantastic-elk-3”
- dataset_digeststring
The dataset digest of the dataset associated with the metric, e.g. an md5 hash of the dataset that uniquely identifies it within datasets of the same name.
- model_idstring
The ID of the logged model or registered model version associated with the metric, if applicable.
- run_idstring
The ID of the run containing the metric.
- paramsarray of object
Run parameters.
Show child attributesHide child attributes
- keystring
Key identifying this param.
- valuestring
Value associated with this param.
- tagsarray of object
Additional metadata key-value pairs.
Show child attributesHide child attributes
- keystring
The tag key.
- valuestring
The tag value.
- inputsobject
Run inputs.
Show child attributesHide child attributes
- dataset_inputsarray of object
Run metrics.
Show child attributesHide child attributes
- tagsarray of object
A list of tags for the dataset input, e.g. a “context” tag with value “training”
- datasetobject
The dataset being used as a Run input.
- model_inputsarray of object
Model inputs to the Run.
Show child attributesHide child attributes
- model_idstring
The unique identifier of the model.
Update GA
POST
Updates run metadata.
API scopes: mlflow
Request body
- run_idstring
ID of the run to update. Must be provided.
- run_uuidstring
[Deprecated, use
run_idinstead] ID of the run to update. This field will be removed in a future MLflow version.
- statusstring
Updated status of the run.
- end_timeint64
Unix timestamp in milliseconds of when the run ended.
- run_namestring
Updated name of the run.
Response
- run_infoobject
Updated metadata of the run.
Show child attributesHide child attributes
- run_idstring
Unique identifier for the run.
- run_uuidstring
[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_idstring
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.
- 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")
Delete GA
Search Runs GA
POST
Searches for runs that satisfy expressions.
Search expressions can use mlflowMetric and mlflowParam keys.
API scopes: mlflow
Request body
- experiment_idsarray of string
List of experiment IDs to search over.
- filterstring
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:
metrics.rmse < 1 and params.model_class = 'LogisticRegression'You can select columns with special characters (hyphen, space, period, etc.) by using double quotes:
metrics."model class" = 'LinearRegression' and tags."user-name" = 'Tomas'Supported operators are
=,!=,>,>=,<, and<=.
- run_view_typestring
Whether to display only active, only deleted, or all runs. Defaults to only active runs.
- max_resultsint32
Maximum number of runs desired. Max threshold is 50000
- order_byarray of string
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_timeDESCfollowed byrun_idfor runs with the same start time (and this is the default ordering criterion if order_by is not provided).
- page_tokenstring
Token for the current page of runs.
Response
Returns a list of Run objects.
Delete Runs GA
POST
Bulk delete runs in an experiment that were created prior to or at the specified timestamp. Deletes at most max_runs per request. To call this API from a Databricks Notebook in Python, you can use the client code snippet on
API scopes: mlflow
Bulk delete runs in an experiment that were created prior to or at the specified timestamp. Deletes at most max_runs per request. To call this API from a Databricks Notebook in Python, you can use the client code snippet on https://docs.databricks.com/en/mlflow/runs.html#bulk-delete.
Bulk delete runs in an experiment that were created prior to or at the specified timestamp. Deletes at most max_runs per request. To call this API from a Databricks Notebook in Python, you can use the client code snippet on https://learn.microsoft.com/en-us/azure/databricks/mlflow/runs#bulk-restore.
Bulk delete runs in an experiment that were created prior to or at the specified timestamp. Deletes at most max_runs per request. To call this API from a Databricks Notebook in Python, you can use the client code snippet on https://docs.gcp.databricks.com/en/mlflow/runs.html#bulk-delete.
Request body
- experiment_idstring
The ID of the experiment containing the runs to delete.
- max_timestamp_millisint64
The maximum creation timestamp in milliseconds since the UNIX epoch for deleting runs. Only runs created prior to or at this timestamp are deleted.
- max_runsint32
An optional positive integer indicating the maximum number of runs to delete. The maximum allowed value for max_runs is 10000.
Response
- runs_deletedint32
The number of runs deleted.
Restore Run GA
Restore Runs GA
POST
Bulk restore runs in an experiment that were deleted no earlier than the specified timestamp. Restores at most max_runs per request. To call this API from a Databricks Notebook in Python, you can use the client code snippet on
API scopes: mlflow
Bulk restore runs in an experiment that were deleted no earlier than the specified timestamp. Restores at most max_runs per request. To call this API from a Databricks Notebook in Python, you can use the client code snippet on https://docs.databricks.com/en/mlflow/runs.html#bulk-restore.
Bulk restore runs in an experiment that were deleted no earlier than the specified timestamp. Restores at most max_runs per request. To call this API from a Databricks Notebook in Python, you can use the client code snippet on https://learn.microsoft.com/en-us/azure/databricks/mlflow/runs#bulk-restore.
Bulk restore runs in an experiment that were deleted no earlier than the specified timestamp. Restores at most max_runs per request. To call this API from a Databricks Notebook in Python, you can use the client code snippet on https://docs.gcp.databricks.com/en/mlflow/runs.html#bulk-restore.
Request body
- experiment_idstring
The ID of the experiment containing the runs to restore.
- min_timestamp_millisint64
The minimum deletion timestamp in milliseconds since the UNIX epoch for restoring runs. Only runs deleted no earlier than this timestamp are restored.
- max_runsint32
An optional positive integer indicating the maximum number of runs to restore. The maximum allowed value for max_runs is 10000.
Response
- runs_restoredint32
The number of runs restored.
Set Tag GA
POST
Sets a tag on a run. Tags are run metadata that can be updated during a run and after a run completes.
API scopes: mlflow
Request body
- run_idstring
ID of the run under which to log the tag. Must be provided.
- run_uuidstring
[Deprecated, use
run_idinstead] ID of the run under which to log the tag. This field will be removed in a future MLflow version.
- keystring
Name of the tag. Keys up to 250 bytes in size are supported.
- valuestring
String value of the tag being logged. Values up to 64KB in size are supported.
Delete Tag GA
POST
Deletes a tag on a run. Tags are run metadata that can be updated during a run and after a run completes.
API scopes: mlflow
Request body
- run_idstring
ID of the run that the tag was logged under. Must be provided.
- keystring
Name of the tag. Maximum size is 255 bytes. Must be provided.
Log Metric GA
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.
API scopes: mlflow
Request body
- run_idstring
ID of the run under which to log the metric. Must be provided.
- run_uuidstring
[Deprecated, use
run_idinstead] ID of the run under which to log the metric. This field will be removed in a future MLflow version.
- keystring
Name of the metric.
- valuedouble
Double value of the metric being logged.
- timestampint64
Unix timestamp in milliseconds at the time metric was logged.
- stepint64
Step at which to log the metric
- model_idstring
ID of the logged model associated with the metric, if applicable
- dataset_namestring
The name of the dataset associated with the metric. E.g. “my.uc.table@2” “nyc-taxi-dataset”, “fantastic-elk-3”
- dataset_digeststring
Dataset digest of the dataset associated with the metric, e.g. an md5 hash of the dataset that uniquely identifies it within datasets of the same name.
Log Param GA
POST
Logs 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.
API scopes: mlflow
Request body
- run_idstring
ID of the run under which to log the param. Must be provided.
- run_uuidstring
[Deprecated, use
run_idinstead] ID of the run under which to log the param. This field will be removed in a future MLflow version.
- keystring
Name of the param. Maximum size is 255 bytes.
- valuestring
String value of the param being logged. Maximum size is 500 bytes.
Log Inputs GA
POST
Logs inputs, such as datasets and models, to an MLflow Run.
API scopes: mlflow
Request body
- run_idstring
ID of the run to log under
- datasetsarray of object
Dataset inputs
Show child attributesHide child attributes
- tagsarray of object
A list of tags for the dataset input, e.g. a “context” tag with value “training”
Show child attributesHide child attributes
- keystring
The tag key.
- valuestring
The tag value.
- datasetobject
The dataset being used as a Run input.
Show child attributesHide child attributes
- namestring
The name of the dataset. E.g. “my.uc.table@2” “nyc-taxi-dataset”, “fantastic-elk-3”
- digeststring
Dataset digest, e.g. an md5 hash of the dataset that uniquely identifies it within datasets of the same name.
- source_typestring
The type of the dataset source, e.g. ‘databricks-uc-table’, ‘DBFS’, ‘S3’, ...
- sourcestring
Source information for the dataset. Note that the source may not exactly reproduce the dataset if it was transformed / modified before use with MLflow.
- schemastring
The schema of the dataset. E.g., MLflow ColSpec JSON for a dataframe, MLflow TensorSpec JSON for an ndarray, or another schema format.
- profilestring
The profile of the dataset. Summary statistics for the dataset, such as the number of rows in a table, the mean / std / mode of each column in a table, or the number of elements in an array.
- modelsarray of object
Model inputs
Show child attributesHide child attributes
- model_idstring
The unique identifier of the model.
Log Batch GA
POST
Logs 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.
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. Specifically, logging a tag is idempotent.
-
Parameters: 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. Specifically, 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 keys, param keys, and tag keys can be up to 250 characters in length
-
Parameter and tag values can be up to 250 characters in length
API scopes: mlflow
Request body
- run_idstring
ID of the run to log under
- metricsarray of object
Metrics to log. A single request can contain up to 1000 metrics, and up to 1000 metrics, params, and tags in total.
Show child attributesHide child attributes
- keystring
The key identifying the metric.
- valuedouble
The value of the metric.
- timestampint64
The timestamp at which the metric was recorded.
- stepint64
The step at which the metric was logged.
- dataset_namestring
The name of the dataset associated with the metric. E.g. “my.uc.table@2” “nyc-taxi-dataset”, “fantastic-elk-3”
- dataset_digeststring
The dataset digest of the dataset associated with the metric, e.g. an md5 hash of the dataset that uniquely identifies it within datasets of the same name.
- model_idstring
The ID of the logged model or registered model version associated with the metric, if applicable.
- run_idstring
The ID of the run containing the metric.
- paramsarray of object
Params to log. A single request can contain up to 100 params, and up to 1000 metrics, params, and tags in total.
Show child attributesHide child attributes
- keystring
Key identifying this param.
- valuestring
Value associated with this param.
- tagsarray of object
Tags to log. A single request can contain up to 100 tags, and up to 1000 metrics, params, and tags in total.
Show child attributesHide child attributes
- keystring
The tag key.
- valuestring
The tag value.
Log Model GA
POST
Note: the Create a logged model API replaces this endpoint.
Log a model to an MLflow Run.
API scopes: mlflow
Request body
- run_idstring
ID of the run to log under
- model_jsonstring
MLmodel file in json format.
Log Outputs GA
POST
Logs outputs, such as models, from an MLflow Run.
API scopes: mlflow
Request body
- run_idstring
The ID of the Run from which to log outputs.
- modelsarray of object
The model outputs from the Run.
Show child attributesHide child attributes
- model_idstring
The unique identifier of the model.
- stepint64
The step at which the model was produced.