Insights

The findings analyses write about a model, each with a summary, a severity and the numbers behind it.

An insight is one finding about a model, written by an analysis: a type, a title, a one-paragraph summary, a severity, a score and a typed payload with the numbers behind it. The dashboard's cards, the notebook cards and kaimei.tabular.plot_insight all draw from the payload.

#The Insight object

severity is info for descriptive findings and low, medium or high for findings that may need attention (robustness, drift, strong interactions). Medium and high insights surface as alerts in the organization and project overviews.

Attributes

idstring

ins_ identifier.

model_id / analysis_idstring

typestring

One of the seven types below.

title / summarystring

Human-readable. Feature names in the summary are back-ticked.

payloadobject

Type-specific numbers; see the table.

scorenumber | null

A headline number: top-3 importance share, interaction strength, robustness score, overall PSI.

severitystring

info, low, medium or high.

created_attimestamp

type	Payload	Severity
`global_importance`	`method` (`permutation` or `occlusion` for images), `features[]` with `importance`, `std`, `metric_drop`, `share` (sums to 1) and `rank`; `n_rows`, `n_repeats`, `n_evals`, `output_std`, `baseline_metric {name, value}`, `population_source`.	info
`partial_dependence`	`features[]` with `type`, `grid` (feature values), `pd` (average output per grid point), `ice` (individual rows' curves), `range` and `monotonicity {direction, consistency}`; `n_rows`, `n_evals`.	info
`interactions`	`pairs[]` of `{features: [a, b], strength}`, strength being the non-additive share of the pair's joint effect; `n_rows`, `n_evals`.	medium when the top strength exceeds 0.25
`robustness`	`epsilon`, `flip_rate` (classifiers) or `relative_change`, `mean_abs_change`, `decision_margin`, `fragile_features[] {feature, sensitivity, flip_rate}`, `score`, `n_rows`, `n_evals`.	high above a 10% flip rate (25% relative change), medium above 3% (10%), else low
`drift`	`features[] {feature, psi, status, reference_mean, current_mean}` sorted by PSI, `overall_psi`, `status` (`stable` < 0.10, `moderate` < 0.25, `significant`, or `insufficient_data`), `drifted_features`, `reference_rows`, `current_rows`, `output_drift {psi, status}`.	low / medium / high by status
`learned_rules`	`rules[] {feature, kind, statement, effect_range, importance_share, consistency}`, one per analysed feature, strongest first; `n_features_analysed`.	info
`behavior`	`n`, `mean`, `std`, `min`, `max`, `quantiles` (5, 25, 50, 75, 95%), `histogram {counts, edges}`; classifiers add `positive_rate`, `threshold`, `near_threshold_rate` and `class_balance`; multiclass adds `quantity: "confidence"` and `low_margin_rate`; `population_source`.	info

The Insight object

{
  "object": "insight",
  "id": "ins_57a85b7ed31073ad0f49",
  "model_id": "mdl_390bd6d9568f626851ef",
  "analysis_id": "anl_b8d673126dcf3cdbe79a",
  "type": "global_importance",
  "title": "Global feature importance",
  "summary": "`credit_score` is the most influential input, followed by `debt_to_income` and `utilization`. Together they account for 59% of the model's output variation (permutation importance over 300 rows).",
  "payload": {
    "method": "permutation",
    "features": [
      {
        "feature": "credit_score",
        "importance": 0.230341,
        "std": 0.01241,
        "metric_drop": 0.123333,
        "share": 0.257933,
        "rank": 1
      },
      {
        "feature": "debt_to_income",
        "importance": 0.147916,
        "std": 0.000341,
        "metric_drop": 0.09,
        "share": 0.165635,
        "rank": 2
      },
      {
        "feature": "utilization",
        "importance": 0.147203,
        "std": 0.002946,
        "metric_drop": 0.07,
        "share": 0.164836,
        "rank": 3
      },
      …
    ],
    "n_rows": 300,
    "n_repeats": 3,
    "n_evals": 8400,
    "output_std": 0.319101,
    "baseline_metric": {"name": "accuracy", "value": 0.79},
    "population_source": "reference_data"
  },
  "score": 0.5884,
  "severity": "info",
  "created_at": "2026-10-31T22:40:23.967453Z"
}

#List insights

GET/v1/insightsAPI key or session

By default the latest insight of each type per model, so one call per model gives its current picture. Pass history=true for every insight ever written, newest first, which is how you compare runs.

Query parameters

modelstringoptional

Model id or slug.

typestringoptional

One insight type.

severitystringoptional

info, low, medium or high.

historybooleanoptionaldefault false

Return every insight instead of the latest per type.

limitintegeroptionaldefault 50

1 to 500.

offsetintegeroptionaldefault 0

Returns

A page of Insights.

for insight in client.insights.list(model="credit-risk-v3").data:
    print(f"{insight.type:20} {insight.severity:7} {insight.summary}")

drift_runs = client.insights.list(model="credit-risk-v3", type="drift", history=True)
print([(i.created_at, i.payload["overall_psi"]) for i in drift_runs.data])

alerts = client.insights.list(severity="high")

curl "https://api.kaimei.ai/v1/insights?model=credit-risk-v3" \
  -H "Authorization: Bearer $KAIMEI_API_KEY"

curl "https://api.kaimei.ai/v1/insights?model=credit-risk-v3&type=drift&history=true&limit=2" \
  -H "Authorization: Bearer $KAIMEI_API_KEY"

200 OKResponse

{
  "object": "list",
  "data": [
    {
      "object": "insight",
      "id": "ins_d47e329c80182e6a72e9",
      "model_id": "mdl_390bd6d9568f626851ef",
      "analysis_id": "anl_b8d673126dcf3cdbe79a",
      "type": "behavior",
      "title": "Output behaviour",
      "summary": "On the reference population the model predicts `decline` 44% of the time; 15% of cases sit within ±0.10 of the decision threshold.",
      "payload": {
        "n": 300,
        "mean": 0.457585,
        "std": 0.319101,
        "min": 0.005089,
        "max": 0.99541,
        "quantiles": {
          "0.05": 0.03834,
          "0.25": 0.150427,
          "0.5": 0.423343,
          "0.75": 0.758318,
          "0.95": 0.961763
        },
        "histogram": {
          "counts": [28, 25, …],
          "edges": [0.005089, 0.054605, …]
        },
        "positive_rate": 0.436667,
        "threshold": 0.5,
        "near_threshold_rate": 0.146667,
        "class_balance": {
          "decline": 0.436667,
          "approve": 0.563333
        },
        "population_source": "reference_data"
      },
      "score": null,
      "severity": "info",
      "created_at": "2026-10-31T22:40:25.338623Z"
    },
    {
      "object": "insight",
      "id": "ins_1836c65e335bf61ce157",
      "model_id": "mdl_390bd6d9568f626851ef",
      "analysis_id": "anl_b8d673126dcf3cdbe79a",
      "type": "learned_rules",
      "title": "What the model has learned",
      "summary": "Higher `credit_score` decreases the probability of decline, most sharply between 543 and 610 (range 14% → 92%).",
      "payload": {
        "rules": [
          {
            "feature": "credit_score",
            "kind": "decreasing",
            "statement": "Higher `credit_score` decreases the probability of decline, most sharply between 543 and 610 (range 14% → 92%).",
            "effect_range": 0.774383,
            "importance_share": 0.257933,
            "consistency": 1.0
          },
          …
        ],
        "n_features_analysed": 6
      },
      "score": null,
      "severity": "info",
      "created_at": "2026-10-31T22:40:25.332034Z"
    },
    {
      "object": "insight",
      "id": "ins_a0a2b5c4a5ddb552758a",
      "type": "drift",
      "title": "Input drift",
      "severity": "medium",
      "score": 0.148039,
      "summary": "Recent traffic has moderate drift (PSI 0.15). Shifted inputs: `loan_amount`, `debt_to_income`, `income`.",
      "payload": …
    },
    …
  ],
  "total": 7,
  "limit": 50,
  "offset": 0,
  "has_more": true
}

#Retrieve an insight

GET/v1/insights/{insight_id}API key or session

One insight by id, with its full payload.

Path parameters

insight_idstringrequired

Returns

An Insight.

insight = client.insights.retrieve("ins_e848f96d11d9a89045f4")
curve = insight.payload["features"][0]
print(curve["feature"], curve["monotonicity"], list(zip(curve["grid"], curve["pd"]))[:3])
insight.to_frame()        # one row per grid point of each curve

curl https://api.kaimei.ai/v1/insights/ins_e848f96d11d9a89045f4 \
  -H "Authorization: Bearer $KAIMEI_API_KEY"

200 OKResponse

{
  "object": "insight",
  "id": "ins_e848f96d11d9a89045f4",
  "model_id": "mdl_390bd6d9568f626851ef",
  "analysis_id": "anl_b8d673126dcf3cdbe79a",
  "type": "partial_dependence",
  "title": "Feature behaviour curves",
  "summary": "Behaviour curves for the 6 most important features. 6 respond monotonically.",
  "payload": {
    "features": [
      {
        "feature": "credit_score",
        "type": "integer",
        "grid": [
          543, 610, 627, 644, 660, 672, 685, 697, 721, 744, 768,
          815
        ],
        "pd": [
          0.915542, 0.703295, 0.637179, 0.572224, 0.514397,
          0.474051, 0.433779, 0.399582, 0.334656, 0.277501,
          0.224315, 0.141159
        ],
        "ice": [
          [0.990147, 0.938966, …],
          [0.871585, 0.50959, …],
          …
        ],
        "range": 0.774383,
        "monotonicity": {
          "direction": "decreasing",
          "consistency": 1.0
        }
      },
      {
        "feature": "utilization",
        "type": "numeric",
        "grid": [0.076, 0.1838, …],
        "pd": [0.256678, 0.307813, …],
        "ice": …,
        "range": 0.484587,
        "monotonicity": {
          "direction": "increasing",
          "consistency": 1.0
        }
      },
      …
    ],
    "n_rows": 200,
    "n_evals": 12600
  },
  "score": null,
  "severity": "info",
  "created_at": "2026-10-31T22:40:24.194133Z"
}