========== 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. .. contents:: Endpoints :local: :depth: 1 ---- List Models ----------- .. code-block:: text GET /api/models **Query Parameters** .. list-table:: :header-rows: 1 :widths: 20 10 10 60 * - 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** .. code-block:: bash curl "$BASE_URL/api/models?project_id=d4e5f6a7-b8c9-0123-def4-567890123456&sort_metric=auc" \ -H "Authorization: Bearer YOUR_API_KEY" .. code-block:: python 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`` .. code-block:: json { "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 ---------------- .. code-block:: text GET /api/models/{model_id} Return model metadata, evaluation metrics, and artifact links. **Example** .. code-block:: bash curl "$BASE_URL/api/models/a7b8c9d0-e1f2-3456-7890-abcdef123456" \ -H "Authorization: Bearer YOUR_API_KEY" **Response** ``200 OK`` .. code-block:: json { "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 ------------------- .. code-block:: text 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** .. code-block:: bash curl "$BASE_URL/api/models/a7b8c9d0-e1f2-3456-7890-abcdef123456/parameters" \ -H "Authorization: Bearer YOUR_API_KEY" **Response** ``200 OK`` .. code-block:: json { "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 -------------------- .. code-block:: text 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** .. code-block:: bash curl "$BASE_URL/api/models/a7b8c9d0-e1f2-3456-7890-abcdef123456/explain" \ -H "Authorization: Bearer YOUR_API_KEY" **Response** ``200 OK`` .. code-block:: json { "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 ----------------------- .. code-block:: text 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** .. list-table:: :header-rows: 1 :widths: 20 10 10 60 * - 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** .. code-block:: bash 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} }' .. code-block:: python 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`` .. code-block:: json { "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 ----------------------- .. code-block:: text 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** .. list-table:: :header-rows: 1 :widths: 20 10 10 60 * - Field - Type - Required - Description * - ``file`` - file - Yes - CSV or Parquet file with input features. **Example** .. code-block:: bash 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`` .. code-block:: json { "row_count": 1000, "predictions": [ {"amount": 29.99, "merchant_id": 42, "pred_predict": "0"}, {"amount": 9500.00, "merchant_id": 7, "pred_predict": "1"} ] } ---- Delete Model ------------ .. code-block:: text DELETE /api/models/{model_id} Permanently delete a model. **Example** .. code-block:: bash curl -X DELETE "$BASE_URL/api/models/a7b8c9d0-e1f2-3456-7890-abcdef123456" \ -H "Authorization: Bearer YOUR_API_KEY" **Response** ``200 OK`` .. code-block:: json { "ok": true } ---- .. seealso:: - :doc:`experiments` -- Viewing all models from an experiment. - :doc:`deployments` -- Deploying a model for serving. - :doc:`studio` -- Running what-if scenarios against a deployed model.