Model Version

View as Markdown

ModelVersion object

namestring: Unique name of the model

versionstring: Model's version number.

creation_timestampint64: Timestamp recorded when this model_version was created.

last_updated_timestampint64: Timestamp recorded when metadata for this model_version was last updated.

user_idstring: User that created this model_version.

current_stagestring: Current stage for this model_version.

descriptionstring: Description of this model_version.

sourcestring: URI indicating the location of the source model artifacts, used when creating model_version

run_idstring: MLflow run ID used when creating model_version, if source was generated by an experiment run stored in MLflow tracking server.

statusstring

Current status of model_version

Values:

PENDING_REGISTRATION
FAILED_REGISTRATION
READY

status_messagestring: Details on current status, if it is pending or failed.

tagsarray of object

Tags: Additional metadata key-value pairs for this model_version.

Show child attributesHide child attributes

keystring: The tag key.

valuestring: The tag value.

run_linkstring: Run Link: Direct link to the run that generated this version

View as Markdown

The ModelVersion object

{
  "name": "string",
  "version": "string",
  "creation_timestamp": 0,
  "last_updated_timestamp": 0,
  "user_id": "string",
  "current_stage": "string",
  "description": "string",
  "source": "string",
  "run_id": "string",
  "status": "PENDING_REGISTRATION",
  "status_message": "string",
  "tags": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "run_link": "string"
}

Get a model version GA

GET /api/2.0/mlflow/model-versions/get

Get a model version.

API scopes: mlflow

Parameters

namestringRequiredquery: Name of the registered model

versionstringRequiredquery: Model version number

Response

model_versionobject

Show child attributesHide child attributes

namestring: Unique name of the model

versionstring: Model's version number.

creation_timestampint64: Timestamp recorded when this model_version was created.

last_updated_timestampint64: Timestamp recorded when metadata for this model_version was last updated.

user_idstring: User that created this model_version.

current_stagestring: Current stage for this model_version.

descriptionstring: Description of this model_version.

sourcestring: URI indicating the location of the source model artifacts, used when creating model_version

run_idstring: MLflow run ID used when creating model_version, if source was generated by an experiment run stored in MLflow tracking server.

statusstring

Current status of model_version

Values:

PENDING_REGISTRATION
FAILED_REGISTRATION
READY

status_messagestring: Details on current status, if it is pending or failed.

tagsarray of object

Tags: Additional metadata key-value pairs for this model_version.

Show child attributesHide child attributes

keystring: The tag key.

valuestring: The tag value.

run_linkstring: Run Link: Direct link to the run that generated this version

View as Markdown

Response

{
  "model_version": {
    "name": "string",
    "version": "string",
    "creation_timestamp": 0,
    "last_updated_timestamp": 0,
    "user_id": "string",
    "current_stage": "string",
    "description": "string",
    "source": "string",
    "run_id": "string",
    "status": "PENDING_REGISTRATION",
    "status_message": "string",
    "tags": [
      {}
    ],
    "run_link": "string"
  }
}

Create a model version GA

POST /api/2.0/mlflow/model-versions/create

Creates a model version.

API scopes: mlflow

Request body

namestringRequired: Register model under this name

sourcestringRequired: URI indicating the location of the model artifacts.

run_idstring: MLflow run ID for correlation, if source was generated by an experiment run in MLflow tracking server

tagsarray of object

Additional metadata for model version.

Show child attributesHide child attributes

keystring: The tag key.

valuestring: The tag value.

run_linkstring: MLflow run link - this is the exact link of the run that generated this model version, potentially hosted at another instance of MLflow.

descriptionstring: Optional description for model version.

Response

model_versionobject

Return new version number generated for this model in registry.

Show child attributesHide child attributes

namestring: Unique name of the model

versionstring: Model's version number.

creation_timestampint64: Timestamp recorded when this model_version was created.

last_updated_timestampint64: Timestamp recorded when metadata for this model_version was last updated.

user_idstring: User that created this model_version.

current_stagestring: Current stage for this model_version.

descriptionstring: Description of this model_version.

sourcestring: URI indicating the location of the source model artifacts, used when creating model_version

run_idstring: MLflow run ID used when creating model_version, if source was generated by an experiment run stored in MLflow tracking server.

statusstring

Current status of model_version

Values:

PENDING_REGISTRATION
FAILED_REGISTRATION
READY

status_messagestring: Details on current status, if it is pending or failed.

tagsarray of object

Tags: Additional metadata key-value pairs for this model_version.

Show child attributesHide child attributes

keystring: The tag key.

valuestring: The tag value.

run_linkstring: Run Link: Direct link to the run that generated this version

View as Markdown

Request

{
  "name": "string",
  "source": "string",
  "run_id": "string",
  "tags": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "run_link": "string",
  "description": "string"
}

Response

{
  "model_version": {
    "name": "string",
    "version": "string",
    "creation_timestamp": 0,
    "last_updated_timestamp": 0,
    "user_id": "string",
    "current_stage": "string",
    "description": "string",
    "source": "string",
    "run_id": "string",
    "status": "PENDING_REGISTRATION",
    "status_message": "string",
    "tags": [
      {}
    ],
    "run_link": "string"
  }
}

Update model version GA

PATCH /api/2.0/mlflow/model-versions/update

Updates the model version.

API scopes: mlflow

Request body

namestringRequired: Name of the registered model

versionstringRequired: Model version number

descriptionstring: If provided, updates the description for this registered_model.

Response

model_versionobject

Return new version number generated for this model in registry.

Show child attributesHide child attributes

namestring: Unique name of the model

versionstring: Model's version number.

creation_timestampint64: Timestamp recorded when this model_version was created.

last_updated_timestampint64: Timestamp recorded when metadata for this model_version was last updated.

user_idstring: User that created this model_version.

current_stagestring: Current stage for this model_version.

descriptionstring: Description of this model_version.

sourcestring: URI indicating the location of the source model artifacts, used when creating model_version

run_idstring: MLflow run ID used when creating model_version, if source was generated by an experiment run stored in MLflow tracking server.

statusstring

Current status of model_version

Values:

PENDING_REGISTRATION
FAILED_REGISTRATION
READY

status_messagestring: Details on current status, if it is pending or failed.

tagsarray of object

Tags: Additional metadata key-value pairs for this model_version.

Show child attributesHide child attributes

keystring: The tag key.

valuestring: The tag value.

run_linkstring: Run Link: Direct link to the run that generated this version

View as Markdown

Request

{
  "name": "string",
  "version": "string",
  "description": "string"
}

Response

{
  "model_version": {
    "name": "string",
    "version": "string",
    "creation_timestamp": 0,
    "last_updated_timestamp": 0,
    "user_id": "string",
    "current_stage": "string",
    "description": "string",
    "source": "string",
    "run_id": "string",
    "status": "PENDING_REGISTRATION",
    "status_message": "string",
    "tags": [
      {}
    ],
    "run_link": "string"
  }
}

Delete a model version GA

DELETE /api/2.0/mlflow/model-versions/delete

Deletes a model version.

API scopes: mlflow

Parameters

namestringRequiredquery: Name of the registered model

versionstringRequiredquery: Model version number

Search model versions GA

GET /api/2.0/mlflow/model-versions/search

Searches for specific model versions based on the supplied filter.

API scopes: mlflow

Parameters

filterstringquery: String filter condition, like "name='my-model-name'". Must be a single boolean condition, with string values wrapped in single quotes.

max_resultsint64<= 10000query: Maximum number of models desired. Max threshold is 10K.
Default: 10000

order_byarray of stringquery: 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_tokenstringquery: Pagination token to go to next page based on previous search query.

Response

Returns a list of ModelVersion objects.

View as Markdown

Response

{
  "model_versions": [
    {
      "name": "string",
      "version": "string",
      "creation_timestamp": 0,
      "last_updated_timestamp": 0,
      "user_id": "string",
      "current_stage": "string",
      "description": "string",
      "source": "string",
      "run_id": "string",
      "status": "PENDING_REGISTRATION",
      "status_message": "string",
      "tags": [
        {}
      ],
      "run_link": "string"
    }
  ],
  "next_page_token": "string"
}

Get a model version URI GA

GET /api/2.0/mlflow/model-versions/get-download-uri

Gets a URI to download the model version.

API scopes: mlflow

Parameters

namestringRequiredquery: Name of the registered model

versionstringRequiredquery: Model version number

Response

artifact_uristring: URI corresponding to where artifacts for this model version are stored.

Set a version tag GA

POST /api/2.0/mlflow/model-versions/set-tag

Sets a model version tag.

API scopes: mlflow

Request body

namestringRequired: Unique name of the model.

versionstringRequired: Model version number.

keystringRequired: Name of the tag. Maximum size depends on storage backend. If a tag with this name already exists, its preexisting value will be replaced by the specified value. All storage backends are guaranteed to support key values up to 250 bytes in size.

valuestringRequired: 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.

Delete a model version tag GA

DELETE /api/2.0/mlflow/model-versions/delete-tag

Deletes a model version tag.

API scopes: mlflow

Parameters

namestringRequiredquery: Name of the registered model that the tag was logged under.

versionstringRequiredquery: Model version number that the tag was logged under.

keystringRequiredquery: Name of the tag. The name must be an exact match; wild-card deletion is not supported. Maximum size is 250 bytes.

Transition a stage GA

POST /api/2.0/mlflow/databricks/model-versions/transition-stage

Transition a model version's stage. This is a <Databricks> workspace version of the MLflow endpoint that also accepts a comment associated with the transition to be recorded.

API scopes: mlflow

Request body

namestring[ 1 .. 100 ] charactersRequired: Name of the model.
Example: search_ads_model

versionstringRequired: Version of the model.
Example: 1

stagestringRequired

Target stage of the transition. Valid values are:

None: The initial stage of a model version.
Staging: Staging or pre-production stage.
Production: Production stage.
Archived: Archived stage.

archive_existing_versionsbooleanRequired: Specifies whether to archive all current model versions in the target stage.
Example: true

commentstring[ 1 .. 65535 ] characters: User-provided comment on the action.
Example: This version is great!

Response

model_version_databricksobject

Updated model version

Show child attributesHide child attributes

namestring[ 1 .. 100 ] characters: Name of the model.
Example: search_ads_model

versionstring: Version of the model.
Example: 1

creation_timestampint64: Creation time of the object, as a Unix timestamp in milliseconds.
Example: 1594437249910

last_updated_timestampint64: Time of the object at last update, as a Unix timestamp in milliseconds.
Example: 1594437549910

user_idstringemail: The username of the user that created the object.
Example: jane.doe@example.com

current_stagestring

descriptionstring<= 65535 characters: User-specified description for the object.
Example: Here's some extra info.

sourcestring: URI that indicates the location of the source model artifacts. This is used when creating the model version.
Example: dbfs:/databricks/mlflow-tracking/run123/model

run_idstringuuid: Unique identifier for the MLflow tracking run associated with the source model artifacts.
Example: 6fc74c92704341aaa49e74dcc6031057

statusstring

The status of the model version. Valid values are:

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.

Values:

PENDING_REGISTRATION
FAILED_REGISTRATION
READY

status_messagestring: Details on the current status, for example why registration failed.
Example: Source could not be found.

open_requestsarray of object

Open requests for this model_versions. Gap in sequence number is intentional and is done in order to match field sequence numbers of ModelVersion proto message

Show child attributesHide child attributes

creation_timestampint64: Creation time of the object, as a Unix timestamp in milliseconds.
Example: 1594437249910

user_idstringemail: The username of the user that created the object.
Example: jane.doe@example.com

activity_typestring

Type of activity. Valid values are:

APPLIED_TRANSITION: User applied the corresponding stage transition.
REQUESTED_TRANSITION: User requested the corresponding stage transition.
CANCELLED_REQUEST: User cancelled an existing transition request.
APPROVED_REQUEST: User approved the corresponding stage transition.
REJECTED_REQUEST: User rejected the coressponding stage transition.
SYSTEM_TRANSITION: For events performed as a side effect, such as archiving existing model versions in a stage.

Values:

APPLIED_TRANSITION
REQUESTED_TRANSITION
CANCELLED_REQUEST
APPROVED_REQUEST
REJECTED_REQUEST
NEW_COMMENT
SYSTEM_TRANSITION

commentstring[ 1 .. 65535 ] characters: User-provided comment associated with the activity, comment, or transition request.
Example: This version is great!

last_updated_timestampint64: Time of the object at last update, as a Unix timestamp in milliseconds.
Example: 1594437549910

from_stagestring

Source stage of the transition (if the activity is stage transition related). Valid values are:

None: The initial stage of a model version.
Staging: Staging or pre-production stage.
Production: Production stage.
Archived: Archived stage.

to_stagestring

Target stage of the transition (if the activity is stage transition related). Valid values are:

None: The initial stage of a model version.
Staging: Staging or pre-production stage.
Production: Production stage.
Archived: Archived stage.

system_commentstring: Comment made by system, for example explaining an activity of type SYSTEM_TRANSITION. It usually describes a side effect, such as a version being archived as part of another version's stage transition, and may not be returned for some activity types.

available_actionsarray of string

Array of actions on the activity allowed for the current viewer.

Values:

APPROVE_TRANSITION_REQUEST
REJECT_TRANSITION_REQUEST
CANCEL_TRANSITION_REQUEST
EDIT_COMMENT
DELETE_COMMENT

idstringuuid: Unique identifier for the object.
Example: 6fc74c92704341aaa49e74dcc6031057

permission_levelstring

Permission level of the requesting user on the object. For what is allowed at each level, see MLflow Model permissions.

Values:

CAN_MANAGE
CAN_EDIT
CAN_READ
CAN_MANAGE_STAGING_VERSIONS
CAN_MANAGE_PRODUCTION_VERSIONS
CAN_CREATE_REGISTERED_MODEL

tagsarray of object

Array of tags that are associated with the model version.

Show child attributesHide child attributes

keystring: The tag key.

valuestring: The tag value.

run_linkstring: URL of the run associated with the model artifacts. This field is set at model version creation time only for model versions whose source run is from a tracking server that is different from the registry server.
Example: https://<databricks-instance>/#mlflow/experiments/28774367/runs/6fc74c92704341aaa49e74dcc6031057

email_subscription_statusstring

Email Subscription Status: This is the subscription status of the user to the model version Users get subscribed by interacting with the model version.

Values:

ALL_EVENTS
DEFAULT
SUBSCRIBED
UNSUBSCRIBED

feature_listobject

Feature lineage of model_version.

Show child attributesHide child attributes

featuresarray of object

Show child attributesHide child attributes

feature_table_namestring: Feature table name

feature_namestring: Feature name

feature_table_idstring: Feature table id

View as Markdown

Request

{
  "name": "search_ads_model",
  "version": "1",
  "stage": "string",
  "archive_existing_versions": true,
  "comment": "This version is great!"
}

Response

{
  "model_version_databricks": {
    "name": "search_ads_model",
    "version": "1",
    "creation_timestamp": 1594437249910,
    "last_updated_timestamp": 1594437549910,
    "user_id": "jane.doe@example.com",
    "current_stage": "string",
    "description": "Here's some extra info.",
    "source": "dbfs:/databricks/mlflow-tracking/run123/model",
    "run_id": "6fc74c92704341aaa49e74dcc6031057",
    "status": "PENDING_REGISTRATION",
    "status_message": "Source could not be found.",
    "open_requests": [
      {}
    ],
    "permission_level": "CAN_MANAGE",
    "tags": [
      {}
    ],
    "run_link": "https://\u003cdatabricks-instance\u003e/#mlflow/experiments/28774367/runs/6fc74c92704341aaa49e74dcc6031057",
    "email_subscription_status": "ALL_EVENTS",
    "feature_list": {}
  }
}

ModelVersion object​

Get a model version GA​

Parameters​

Response​

Create a model version GA​

Request body​

Response​

Update model version GA​

Request body​

Response​

Delete a model version GA​

Parameters​

Search model versions GA​

Parameters​

Response​

Get a model version URI GA​

Parameters​

Response​

Set a version tag GA​

Request body​

Delete a model version tag GA​

Parameters​

Transition a stage GA​

Request body​

Response​

ModelVersion object

Get a model version GA

Parameters

Response

Create a model version GA

Request body

Response

Update model version GA

Request body

Response

Delete a model version GA

Parameters

Search model versions GA

Parameters

Response

Get a model version URI GA

Parameters

Response

Set a version tag GA

Request body

Delete a model version tag GA

Parameters

Transition a stage GA

Request body

Response