Get model version API

You can use this API to get the metadata of a particular version of a model.

HTTP method and URI path

GET /v3/ml_assets/models/{model_id}/versions/{version_id}

Where:

model_id identifies the model ID and version_id identifies the model version ID.

Standard headers

Use the following standard HTTP header with this request:

Content-Type: application/json

Authorization: <Bearer token>

Required authorizations

The user ID associated with the token which is specified in the request header needs to be granted with one of the following roles:

  • sysadm
  • mladm
  • appuser
  • apiuser (only if the model was created by the user)
  • devuser (only if the model was created by the user)

Expected response

On completion, the service returns an HTTP response, which includes a status code that indicates whether your request is completed. Status code 200 indicates a successful completion. A status code of 4nn or 5nn indicates an error.

The response is a model version output with fields described in Table 1.
Table 1. Response from a successful request

In this table, the Field column and Subfield columns list the returned fields, and the Description column provides a brief description of the field.
Field Subfield Description
entity name The name of the model.
author

The author of the model creation.

name: The name of the author of the model.
description The description of the model.
model_url The URL of the model which contains the model ID.
framework

The framework used to create the model. The framework includes the framework’s name, version, and runtimes.

  • name
    • Framework name for the model.
  • Supported frameworks:
    • mllib, ml, pmml, scikit-learn, xgboost, scikit-learn-pmml, xgboost-pmml, arima and sarimax.
  • version
    • Framework version for the specified framework. Supported versions:
      • 3.4.x or 3.5.x for ML or MLlib
      • 1.2.x or 1.3.x for scikit-learn
      • 0.72.x for scikit-learn-pmml
      • 1.7.x for xgboost
      • 0.9.x for xgboost-pmml
      • 1.15.x or 1.16.x for onnx
      • 0.14.x for arima / sarimax
      • No restriction for other supported frameworks.
  • runtimes
    • This runtimes array specifies the runtime list that a model uses for training. For each runtime information, it consists of:
      • name: runtime name for model training.
      • Supported runtime names: spark, python, java.
      • version: runtime version for model training.
      • Supported runtime versions: 4.0 for spark, mainly for mllib framework.
      • 3.13 for python, mainly for scikit-learn or xgboost model framework.
      • 17 or 21 for java, mainly for pmml or onnx framework.
      • customName (optional for String): the customized runtime name.
      • _id (optional for String): the customized runtime ID.
  • zaiu (boolean): Indicates if the model is eligible for scoring using IBM® z16™ on-chip AI accelerator. This flag is returned for ONNX models only.
  • telum2 (boolean): Indicates if the model is eligible for scoring using the IBM z17™ on-chip AI accelerator. This flag is returned for ONNX models only.
training_definition_url Training definition created for this model. It is only for Spark runtime model.
versionSeq The version sequence number of the returned version of the model.
model_type The value is standard. It means that the model was created from standard MLz’s API.
label_column The label column for the model.
prediction_column The prediction column for the model.
probability_column The probability column for the model.
model_version

The latest model version’s partial important information.

  • content_url: the model’s content URL for this version of the model. The content_url can be used to fetch the model’s content.
  • evaluation_metrics_url: The evaluation metrics URL for this version of the model. The evaluation_metrics_url can be used to fetch the evaluation metrics of this version of the model if the model has evaluation history.
  • guid: The ID of this version of the model.
  • url: the model version URL which contains the model ID and model version ID.
  • version_status: the status of this version of the model. It contains the version state and failure.
  • size: the cost number of model training. It contains the model_in_memory, peak_os_memory, and peak_heap_memory factors.
training_info

The training info for this model.

  • projectId (optional for String): project ID if you need to save the project where the model was trained.
  • originType (optional for String): the type of training runtime for the model trained. For example, the notebook. This value depends on user’s training platform self-definition.
  • originId (optional for String): the training toolkit identifier for the model trained. For example, the notebook ID. This value depends on user’s training platform self-definition.
training_data_schema The training data schema for this model version.
input_data_schema The input data schema for this model version.
metadata guid The model version ID.
created_at The creation timestamp for this model.
modified_at The timestamp of the last modification of the model.
url The URL of this model version.
Response example of a successful request: 
{
  "entity": {
    "prediction_column": "prediction",
    "author": {
      "name": "mlz04"
    },
    "name": "imported_model_mladm",
    "model_url": "https://127.0.0.1:11443/v3/ml_assets/models/0e177db5-239a-43b9-81a6-10e8a49eda00",
    "training_definition_url": "https://127.0.0.1:11443/v3/ml_assets/training_definitions/5b0d4eb2-5396-4741-8174-c46c0bc81369/versions/40203584-1d3c-4943-968d-690d53b8ca00",
    "description": "",
    "training_data_schema": {
      "fields": [
        {
          "metadata": {
            "name": "CUST_ID",
            "scale": 0
          },
          "name": "CUST_ID",
          "nullable": true,
          "type": "long"
        },
        {
          "metadata": {
            "name": "SEX",
            "scale": 0
          },
          "name": "SEX",
          "nullable": true,
          "type": "string"
        },
        {
          "metadata": {
            "name": "AGE",
            "scale": 0
          },
          "name": "AGE",
          "nullable": true,
          "type": "integer"
        },
        {
          "metadata": {
            "name": "EDUCATION",
            "scale": 0
          },
          "name": "EDUCATION",
          "nullable": true,
          "type": "integer"
        },
        {
          "metadata": {
            "name": "INVESTMENT",
            "scale": 2
          },
          "name": "INVESTMENT",
          "nullable": true,
          "type": "decimal(13,2)"
        },
        {
          "metadata": {
            "name": "INCOME",
            "scale": 2
          },
          "name": "INCOME",
          "nullable": true,
          "type": "decimal(13,2)"
        },
        {
          "metadata": {
            "name": "ACTIVITY",
            "scale": 0
          },
          "name": "ACTIVITY",
          "nullable": true,
          "type": "integer"
        },
        {
          "metadata": {
            "name": "CHURN",
            "scale": 0
          },
          "name": "CHURN",
          "nullable": true,
          "type": "integer"
        },
        {
          "metadata": {
            "name": "YRLY_AMT",
            "scale": 2
          },
          "name": "YRLY_AMT",
          "nullable": true,
          "type": "decimal(13,2)"
        },
        {
          "metadata": {
            "name": "AVG_DAILY_TX",
            "scale": 0
          },
          "name": "AVG_DAILY_TX",
          "nullable": true,
          "type": "double"
        },
        {
          "metadata": {
            "name": "YRLY_TX",
            "scale": 0
          },
          "name": "YRLY_TX",
          "nullable": true,
          "type": "integer"
        },
        {
          "metadata": {
            "name": "AVG_TX_AMT",
            "scale": 2
          },
          "name": "AVG_TX_AMT",
          "nullable": true,
          "type": "decimal(13,2)"
        },
        {
          "metadata": {
            "name": "NEGTWEETS",
            "scale": 0
          },
          "name": "NEGTWEETS",
          "nullable": true,
          "type": "integer"
        },
        {
          "metadata": {
            "name": "STATE",
            "scale": 0
          },
          "name": "STATE",
          "nullable": true,
          "type": "string"
        },
        {
          "metadata": {
            "name": "EDUCATION_GROUP",
            "scale": 0
          },
          "name": "EDUCATION_GROUP",
          "nullable": true,
          "type": "string"
        },
        {
          "metadata": {
            "name": "TWITTERID",
            "scale": 0
          },
          "name": "TWITTERID",
          "nullable": true,
          "type": "string"
        },
        {
          "metadata": {
            "name": "CHURN_LABEL",
            "scale": 0
          },
          "name": "CHURN_LABEL",
          "nullable": true,
          "type": "string"
        }
      ],
      "type": "struct"
    },
    "label_column": "CHURN_LABEL",
    "framework": {
      "name": "mllib",
      "version": "4.0",
      "runtimes": [
        {
          "name": "spark",
          "version": "4.0"
        }
      ]
    },
    "probability_column": "probability",
    "training_info": {
      "evaluation": {
        "next_fire_time": "",
        "status": "UNINITIALIZED"
      },
      "originId": "",
      "originType": "",
      "projectId": ""
    },
    "model_version": {
      "content_status": {
        "state": "no_content"
      },
      "content_url": "https://127.0.0.1:11443/v3/ml_assets/models/0e177db5-239a-43b9-81a6-10e8a49eda00/versions/7ca00397-867c-4e67-bd08-91c71cce61e6/content",
      "evaluation_metrics_url": "https://127.0.0.1:11443/v3/ml_assets/models/0e177db5-239a-43b9-81a6-10e8a49eda00/versions/7ca00397-867c-4e67-bd08-91c71cce61e6/evaluation_metrics",
      "guid": "7ca00397-867c-4e67-bd08-91c71cce61e6",
      "url": "https://127.0.0.1:11443/v3/ml_assets/models/0e177db5-239a-43b9-81a6-10e8a49eda00/versions/7ca00397-867c-4e67-bd08-91c71cce61e6",
      "version_status": {
        "failure": "",
        "state": "active"
      }
    },
    "model_type": "standard",
    "versionSeq": 1,
    "input_data_schema": {
      "fields": [
        {
          "metadata": {
            "name": "CUST_ID",
            "scale": 0
          },
          "name": "CUST_ID",
          "nullable": true,
          "type": "long"
        },
        {
          "metadata": {
            "name": "SEX",
            "scale": 0
          },
          "name": "SEX",
          "nullable": true,
          "type": "string"
        },
        {
          "metadata": {
            "name": "AGE",
            "scale": 0
          },
          "name": "AGE",
          "nullable": true,
          "type": "integer"
        },
        {
          "metadata": {
            "name": "EDUCATION",
            "scale": 0
          },
          "name": "EDUCATION",
          "nullable": true,
          "type": "integer"
        },
        {
          "metadata": {
            "name": "INVESTMENT",
            "scale": 2
          },
          "name": "INVESTMENT",
          "nullable": true,
          "type": "decimal(13,2)"
        },
        {
          "metadata": {
            "name": "INCOME",
            "scale": 2
          },
          "name": "INCOME",
          "nullable": true,
          "type": "decimal(13,2)"
        },
        {
          "metadata": {
            "name": "ACTIVITY",
            "scale": 0
          },
          "name": "ACTIVITY",
          "nullable": true,
          "type": "integer"
        },
        {
          "metadata": {
            "name": "CHURN",
            "scale": 0
          },
          "name": "CHURN",
          "nullable": true,
          "type": "integer"
        },
        {
          "metadata": {
            "name": "YRLY_AMT",
            "scale": 2
          },
          "name": "YRLY_AMT",
          "nullable": true,
          "type": "decimal(13,2)"
        },
        {
          "metadata": {
            "name": "AVG_DAILY_TX",
            "scale": 0
          },
          "name": "AVG_DAILY_TX",
          "nullable": true,
          "type": "double"
        },
        {
          "metadata": {
            "name": "YRLY_TX",
            "scale": 0
          },
          "name": "YRLY_TX",
          "nullable": true,
          "type": "integer"
        },
        {
          "metadata": {
            "name": "AVG_TX_AMT",
            "scale": 2
          },
          "name": "AVG_TX_AMT",
          "nullable": true,
          "type": "decimal(13,2)"
        },
        {
          "metadata": {
            "name": "NEGTWEETS",
            "scale": 0
          },
          "name": "NEGTWEETS",
          "nullable": true,
          "type": "integer"
        },
        {
          "metadata": {
            "name": "STATE",
            "scale": 0
          },
          "name": "STATE",
          "nullable": true,
          "type": "string"
        },
        {
          "metadata": {
            "name": "EDUCATION_GROUP",
            "scale": 0
          },
          "name": "EDUCATION_GROUP",
          "nullable": true,
          "type": "string"
        },
        {
          "metadata": {
            "name": "TWITTERID",
            "scale": 0
          },
          "name": "TWITTERID",
          "nullable": true,
          "type": "string"
        }
      ],
      "type": "struct"
    }
  },
  "metadata": {
    "created_at": "2023-07-13T06:40:15.253Z",
    "guid": "7ca00397-867c-4e67-bd08-91c71cce61e6",
    "model_status": [],
    "modified_at": "2023-07-13T06:40:15.253Z",
    "url": "https://127.0.0.1:11443/v3/ml_assets/models/0e177db5-239a-43b9-81a6-10e8a49eda00/versions/7ca00397-867c-4e67-bd08-91c71cce61e6"
  }
}