Models API

Models are machine learning models produced by AutoML experiments. Each model stores its algorithm type, evaluation metrics, and a binary artifact that can be used for predictions.

---

List Models

GET /api/models

Query Parameters

Parameter	Type	Default	Description
project_id	string	–	Filter by project.
experiment_id	string	–	Filter by experiment.
model_type	string	–	Filter by algorithm (e.g. GBM, XGBoost, GLM).
is_best	boolean	–	Only return the best model per experiment.
is_production	boolean	–	Only return models with an active production deployment.
is_staging	boolean	–	Only return models with an active staging deployment.
search	string	–	Search in model name, algorithm, experiment name, project name.
limit	integer	50	Max items.
offset	integer	0	Pagination offset.
sort_metric	string	–	Sort by a metric value: auc, rmse, mae, r2, logloss, accuracy, mse, mean_per_class_error.
sort_dir	string	desc	asc or desc.

Example

curl "$BASE_URL/api/models?project_id=d4e5f6a7-b8c9-0123-def4-567890123456&sort_metric=auc" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

resp = requests.get(f"{BASE_URL}/api/models", headers={
    "Authorization": "Bearer YOUR_API_KEY",
}, params={
    "project_id": "d4e5f6a7-b8c9-0123-def4-567890123456",
    "sort_metric": "auc",
    "sort_dir": "desc",
    "limit": 5,
})
for m in resp.json()["items"]:
    print(f"{m['algo']}: AUC={m['metrics'].get('auc')}")

Response 200 OK

{
  "items": [
    {
      "id": "a7b8c9d0-e1f2-3456-7890-abcdef123456",
      "name": "GBM_1_AutoML",
      "algo": "GBM",
      "experiment_id": "b8c9d0e1-f2a3-4567-8901-bcdef1234567",
      "experiment_name": "Fraud Detection AutoML",
      "project_id": "d4e5f6a7-b8c9-0123-def4-567890123456",
      "project_name": "Fraud Detection v2",
      "is_best": true,
      "is_production": true,
      "is_staging": false,
      "metrics": {
        "auc": 0.982,
        "logloss": 0.071,
        "accuracy": 0.965
      },
      "created_at": "2026-02-12T10:35:00Z"
    }
  ],
  "total": 12,
  "limit": 5,
  "offset": 0
}

---

Get Model Detail

GET /api/models/{model_id}

Return model metadata, evaluation metrics, and artifact links.

Example

curl "$BASE_URL/api/models/a7b8c9d0-e1f2-3456-7890-abcdef123456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "model": {
    "id": "a7b8c9d0-e1f2-3456-7890-abcdef123456",
    "name": "GBM_1_AutoML",
    "algo": "GBM",
    "experiment_id": "b8c9d0e1-f2a3-4567-8901-bcdef1234567",
    "artifact_id": "c9d0e1f2-a3b4-5678-9012-cdef23456789",
    "metrics": {
      "auc": 0.982,
      "logloss": 0.071,
      "accuracy": 0.965,
      "confusion_matrix": {
        "labels": ["0", "1"],
        "matrix": [[48500, 200], [150, 1150]]
      },
      "variable_importance": [
        {"variable": "amount", "percentage": 0.45},
        {"variable": "merchant_id", "percentage": 0.30}
      ]
    }
  },
  "artifact_links": [
    {
      "artifact_id": "c9d0e1f2-a3b4-5678-9012-cdef23456789",
      "owner_type": "model",
      "label": "model_binary"
    }
  ]
}

---

Get Hyperparameters

GET /api/models/{model_id}/parameters

Return the hyperparameters used to train the model. If not stored in metadata, they are loaded from the H2O model artifact.

Example

curl "$BASE_URL/api/models/a7b8c9d0-e1f2-3456-7890-abcdef123456/parameters" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "parameters": {
    "ntrees": {"default": 50, "actual": 150},
    "max_depth": {"default": 5, "actual": 8},
    "learn_rate": {"default": 0.1, "actual": 0.05},
    "sample_rate": {"default": 1.0, "actual": 0.8}
  }
}

---

Model Explainability

GET /api/models/{model_id}/explain

Return structured explainability data for a single model: variable importance, SHAP values, confusion matrix, ROC curve, precision-recall curve, scoring history, and more.

Example

curl "$BASE_URL/api/models/a7b8c9d0-e1f2-3456-7890-abcdef123456/explain" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "explain": {
    "model_id": "a7b8c9d0-e1f2-3456-7890-abcdef123456",
    "algo": "GBM",
    "variable_importance": [
      {"variable": "amount", "percentage": 0.45, "scaled_importance": 1.0},
      {"variable": "merchant_id", "percentage": 0.30, "scaled_importance": 0.67}
    ],
    "shap_summary": null,
    "confusion_matrix": {
      "labels": ["0", "1"],
      "matrix": [[48500, 200], [150, 1150]]
    },
    "roc_curve": {
      "fpr": [0.0, 0.004, 0.01, 1.0],
      "tpr": [0.0, 0.85, 0.95, 1.0]
    },
    "scoring_history": [
      {"timestamp": "2026-02-12T10:31:00Z", "training_logloss": 0.35, "validation_logloss": 0.38}
    ]
  }
}

---

Single/Batch Prediction

POST /api/models/{model_id}/predict

Run predictions directly on a model (without a deployment). Accepts a single input dict or a list of input dicts.

Request Body

Field	Type	Required	Description
inputs	dict or list[dict]	Yes	Feature values. Single record (dict) or batch (list of dicts).
options	object	No	Options. Set include_contributions: true for SHAP-style feature contributions (not available for StackedEnsemble models).

Example

curl -X POST "$BASE_URL/api/models/a7b8c9d0-e1f2-3456-7890-abcdef123456/predict" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {"amount": 29.99, "merchant_id": 42, "hour": 14},
      {"amount": 9500.00, "merchant_id": 7, "hour": 3}
    ],
    "options": {"include_contributions": true}
  }'

resp = requests.post(
    f"{BASE_URL}/api/models/a7b8c9d0-e1f2-3456-7890-abcdef123456/predict",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "inputs": [
            {"amount": 29.99, "merchant_id": 42, "hour": 14},
            {"amount": 9500.00, "merchant_id": 7, "hour": 3},
        ],
        "options": {"include_contributions": True},
    },
)
for pred in resp.json()["predictions"]:
    print("Prediction:", pred["prediction"])

Response 200 OK

{
  "predictions": [
    {"prediction": "0"},
    {"prediction": "1"}
  ],
  "contributions": [
    [
      {"feature": "amount", "value": -0.32},
      {"feature": "merchant_id", "value": -0.15},
      {"feature": "BiasTerm", "value": -1.20}
    ],
    [
      {"feature": "amount", "value": 1.85},
      {"feature": "hour", "value": 0.92},
      {"feature": "BiasTerm", "value": -1.20}
    ]
  ]
}

---

Batch Predict from File

POST /api/models/{model_id}/predict/batch

Upload a CSV or Parquet file and receive predictions for all rows. Uses multipart/form-data.

Form Fields

Field	Type	Required	Description
file	file	Yes	CSV or Parquet file with input features.

Example

curl -X POST "$BASE_URL/api/models/a7b8c9d0-e1f2-3456-7890-abcdef123456/predict/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@new_transactions.csv"

Response 200 OK

{
  "row_count": 1000,
  "predictions": [
    {"amount": 29.99, "merchant_id": 42, "pred_predict": "0"},
    {"amount": 9500.00, "merchant_id": 7, "pred_predict": "1"}
  ]
}

---

Delete Model

DELETE /api/models/{model_id}

Permanently delete a model.

Example

curl -X DELETE "$BASE_URL/api/models/a7b8c9d0-e1f2-3456-7890-abcdef123456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "ok": true
}

---

See also

• Experiments API – Viewing all models from an experiment.

• Deployments API – Deploying a model for serving.

• ML Studio (What-If) API – Running what-if scenarios against a deployed model.