Feature Importance

Page Outline

• Path Parameters
• Query Parameters
• Behavior
• Response

---

Returns the ranked feature importance scores computed during training, indicating which input features had the greatest influence on the model's predictions.

Base Path: /api/v1/models

Method: GET

Path: /{model_id}/training-metrics/feature-importance

Alias: /{model_id}/training/metrics/feature-importance

Auth: Requires a valid Bearer token (Authorization: Bearer <JWT>)

Path Parameters

Parameter	Type	Description
model_id	string	Unique identifier of the model

Query Parameters

Parameter	Type	Default	Description
run_id	string	—	Specific training run ID. Defaults to the most recent completed run
version_id	string	—	Retrieve by version ID. Takes precedence over run_id if both are supplied
top_n	integer	—	Return only the top N features by importance score
method	string	gain	Importance method: gain, split, shap (algorithm-dependent availability)

Behavior

• Feature importance is only available for tree-based algorithms (XGBoost, LightGBM, Random Forest). For linear/logistic models, coefficient magnitudes are returned instead.
• shap method requires that SHAP values were computed during training (opt-in via config.compute_shap: true). Returns HTTP 422 if SHAP was not computed.
• Scores are normalized to sum to 1.0.
• Alias path /training/metrics/feature-importance is fully supported.
• Returns HTTP 404 if the model or run is not found.

Response

Returns a FeatureImportance object.

{
  "model_id": "mdl-7f3a19bc",
  "run_id": "run-20260313-a4b9c2",
  "method": "gain",
  "features": [
    { "feature": "tenure", "importance": 0.412, "rank": 1 },
    { "feature": "monthly_spend", "importance": 0.298, "rank": 2 },
    { "feature": "age", "importance": 0.189, "rank": 3 },
    { "feature": "support_tickets", "importance": 0.101, "rank": 4 }
  ]
}