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,
      "threshold": 0.1842,
      "metric_context": {
        "operating_threshold_metric": "max_f1",
        "operating_threshold": 0.1842,
        "split": "training"
      },
      "confusion_matrix": {
        "labels": ["0", "1"],
        "matrix": [[48500, 200], [150, 1150]]
      },
      "variable_importance": [
        {"variable": "amount", "percentage": 0.45},
        {"variable": "merchant_id", "percentage": 0.30}
      ]
    },
    "is_staging": true,
    "staging_deployment_id": "d0e1f2a3-b4c5-6789-0123-def456789012"
  },
  "deployments": [{
    "id": "d0e1f2a3-b4c5-6789-0123-def456789012",
    "stage": "staging",
    "is_active": true
  }],
  "artifact_links": [
    {
      "artifact_id": "c9d0e1f2-a3b4-5678-9012-cdef23456789",
      "owner_type": "model",
      "label": "model_binary"
    }
  ]
}

For binary models, every threshold-dependent metric and the confusion matrix refer to the same persisted operating threshold. The context identifies how the threshold was selected and which split produced the metrics. Active deployment lineage is returned with model detail, including staging deployments.

---

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.