Analyses

Analyses

Background studies of a whole model that write insights: importance, behaviour, interactions, robustness, drift, rules and performance.

An analysis studies a model as a whole against its reference population (or its logged predictions when it has none) and writes one insight per step. It runs in the background: create it, poll until status is completed or failed, then read the insights.

#The Analysis object

Status moves queued → running → completed or failed; progress is the fraction of steps done and insight_ids fills in when the run completes.

Attributes

idstring
anl_ identifier.
model_idstring

typestring

The requested type, see below.

statusstring
queued, running, completed or failed.
progressnumber

0 to 1.

optionsobject

The options used.

errorstring | null

Why it failed, when it did (for example At least 5 reference rows are needed…).

insight_idsarray of strings

The insights produced.

n_evalsinteger

Model evaluations spent so far.

created_at / started_at / completed_attimestamp

typeRunsProduces
fullEvery step below, in orderSeven insights; eight once predictions have outcomes
global_importancePermutation importance over the population; with labels, also the drop in accuracy or R².global_importance
partial_dependenceImportance first, then behaviour (partial dependence and individual) curves for the top_features most important features.global_importance, partial_dependence
interactionsImportance first, then pairwise non-additivity among the top features.global_importance, interactions
robustnessOutputs and decisions under epsilon-σ input noise.robustness
driftReference rows vs the latest window logged predictions, by PSI.drift
learned_rulesImportance and curves first, then one plain-English rule per feature.global_importance, partial_dependence, learned_rules
behaviorDistribution of the outputs over the population.behavior
performanceThe newest window outcomes against a baseline: the outcomes before them, or the labelled reference rows. Flags a drop larger than chance explains.performance

Image models run only global_importance (patch occlusion), behavior, drift and performance; pixel-wise permutation is not a meaningful question for a picture. A population of at least 5 rows is required; drift additionally needs 20 reference rows and 20 logged predictions. performance on its own needs neither and works for models Kaimei can't run, as long as predictions have outcomes.

The Analysis object
{
  "object": "analysis",
  "id": "anl_b8d673126dcf3cdbe79a",
  "model_id": "mdl_390bd6d9568f626851ef",
  "type": "full",
  "status": "completed",
  "progress": 1.0,
  "options": {
    "max_rows": 300,
    "top_features": 6,
    "grid_size": 12,
    "n_repeats": 3,
    "epsilon": 0.05,
    "window": 500,
    "seed": 0
  },
  "error": null,
  "insight_ids": [
    "ins_57a85b7ed31073ad0f49", "ins_e848f96d11d9a89045f4",
    "ins_020e5f253b06ef6ec984", "ins_5b3ab8b1490030b622d6",
    "ins_a0a2b5c4a5ddb552758a", "ins_1836c65e335bf61ce157",
    "ins_d47e329c80182e6a72e9"
  ],
  "n_evals": 101558,
  "created_at": "2026-10-31T22:40:23.831817Z",
  "started_at": "2026-10-31T22:40:23.838319Z",
  "completed_at": "2026-10-31T22:40:25.340129Z"
}

#Start an analysis

POST/v1/analysesAPI key or session

Queue a study of the model. Returns 202 immediately with status: "queued". Counts against the monthly analyses quota and the 30-per-hour limit. A restart resumes a job that was still running. After three interrupted attempts the job fails and can be started again.

Body parameters

modelstringrequired

Model id or slug.

typestringoptionaldefault "full"

One of the types above.

optionsobjectoptional

max_rowsintegeroptionaldefault 400

Cap on population rows used, 10 to 5000; subsampled when the population is bigger.

top_featuresintegeroptionaldefault 6

Features studied in depth by partial dependence and interactions, 1 to 30 (interactions use at most 6).

grid_sizeintegeroptionaldefault 12

Points per behaviour curve, 3 to 50.

n_repeatsintegeroptionaldefault 3

Permutation repeats for importance, 1 to 10.

epsilonnumberoptionaldefault 0.05

Robustness noise, as a fraction of each feature's standard deviation, up to 1.

windowintegeroptionaldefault 500

Drift: recent logged predictions compared with the reference set. Performance: recent outcomes compared with the baseline; with low traffic a smaller window reacts sooner to a recent drop. 20 to 10000.

baselinestringoptionaldefault "earlier_traffic"

Performance: earlier_traffic (the up to 5,000 outcomes before the window) or reference_data (the model scored on its labelled reference rows; needs a model Kaimei can run, and reference rows are often training data, which flatters it).

seedintegeroptional

Reproducible sampling.

Returns

The Analysis. 202.
analysis = client.analyses.create(model="credit-risk-v3", type="full",
                                  options={"max_rows": 300, "top_features": 6, "seed": 0})
analysis = client.analyses.wait(analysis.id, timeout=300, interval=1.5)
print(analysis.status, analysis.progress, len(analysis.insight_ids))
# completed 1.0 7
curl -X POST https://api.kaimei.ai/v1/analyses \
  -H "Authorization: Bearer $KAIMEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "credit-risk-v3", "type": "full", "options": {"max_rows": 300, "top_features": 6, "seed": 0}}'
202 AcceptedResponse
{
  "object": "analysis",
  "id": "anl_b8d673126dcf3cdbe79a",
  "model_id": "mdl_390bd6d9568f626851ef",
  "type": "full",
  "status": "queued",
  "progress": 0.0,
  "options": {
    "max_rows": 300,
    "top_features": 6,
    "grid_size": 12,
    "n_repeats": 3,
    "epsilon": 0.05,
    "window": 500,
    "seed": 0
  },
  "error": null,
  "insight_ids": [],
  "n_evals": 0,
  "created_at": "2026-10-31T22:40:23.831817Z",
  "started_at": null,
  "completed_at": null
}

#List analyses

GET/v1/analysesAPI key or session

Analyses in your organization, newest first.

Query parameters

modelstringoptional

Model id or slug.

statusstringoptional
queued, running, completed or failed.
limitintegeroptionaldefault 20

1 to 200.

offsetintegeroptionaldefault 0

Returns

A page of Analyses.
running = client.analyses.list(status="running").total
for analysis in client.analyses.iterate(model="credit-risk-v3"):
    print(analysis.type, analysis.status, analysis.completed_at)
curl "https://api.kaimei.ai/v1/analyses?model=credit-risk-v3&limit=2" \
  -H "Authorization: Bearer $KAIMEI_API_KEY"
200 OKResponse
{
  "object": "list",
  "data": [
    {
      "object": "analysis",
      "id": "anl_b8d673126dcf3cdbe79a",
      "model_id": "mdl_390bd6d9568f626851ef",
      "type": "full",
      "status": "completed",
      "progress": 1.0,
      "options": {
        "max_rows": 300,
        "top_features": 6,
        "grid_size": 12,
        "n_repeats": 3,
        "epsilon": 0.05,
        "window": 500,
        "seed": 0
      },
      "error": null,
      "insight_ids": [
        "ins_57a85b7ed31073ad0f49", "ins_e848f96d11d9a89045f4",
        "ins_020e5f253b06ef6ec984", "ins_5b3ab8b1490030b622d6",
        "ins_a0a2b5c4a5ddb552758a", "ins_1836c65e335bf61ce157",
        "ins_d47e329c80182e6a72e9"
      ],
      "n_evals": 101558,
      "created_at": "2026-10-31T22:40:23.831817Z",
      "started_at": "2026-10-31T22:40:23.838319Z",
      "completed_at": "2026-10-31T22:40:25.340129Z"
    },
    {
      "object": "analysis",
      "id": "anl_376eff53d472460768b8",
      "model_id": "mdl_390bd6d9568f626851ef",
      "type": "full",
      "status": "completed",
      "progress": 1.0,
      "options": {"seed": 7},
      "error": null,
      "insight_ids": …,
      "n_evals": 100132,
      "created_at": "2026-10-31T22:37:25.685070Z",
      "started_at": "2026-10-31T22:37:25.688109Z",
      "completed_at": "2026-10-31T22:37:26.872969Z"
    }
  ],
  "total": 2,
  "limit": 2,
  "offset": 0,
  "has_more": false
}

#Retrieve an analysis

GET/v1/analyses/{analysis_id}API key or session

One analysis by id. Poll this until status leaves queued and running.

Path parameters

analysis_idstringrequired

Returns

An Analysis.
import time
analysis = client.analyses.retrieve("anl_b8d673126dcf3cdbe79a")
while analysis.status in ("queued", "running"):
    time.sleep(1.5)
    analysis = client.analyses.retrieve(analysis.id)
# or simply: client.analyses.wait(analysis.id)
curl https://api.kaimei.ai/v1/analyses/anl_b8d673126dcf3cdbe79a \
  -H "Authorization: Bearer $KAIMEI_API_KEY"
200 OKResponse
{
  "object": "analysis",
  "id": "anl_b8d673126dcf3cdbe79a",
  "model_id": "mdl_390bd6d9568f626851ef",
  "type": "full",
  "status": "completed",
  "progress": 1.0,
  "options": {
    "max_rows": 300,
    "top_features": 6,
    "grid_size": 12,
    "n_repeats": 3,
    "epsilon": 0.05,
    "window": 500,
    "seed": 0
  },
  "error": null,
  "insight_ids": [
    "ins_57a85b7ed31073ad0f49", "ins_e848f96d11d9a89045f4",
    "ins_020e5f253b06ef6ec984", "ins_5b3ab8b1490030b622d6",
    "ins_a0a2b5c4a5ddb552758a", "ins_1836c65e335bf61ce157",
    "ins_d47e329c80182e6a72e9"
  ],
  "n_evals": 101558,
  "created_at": "2026-10-31T22:40:23.831817Z",
  "started_at": "2026-10-31T22:40:23.838319Z",
  "completed_at": "2026-10-31T22:40:25.340129Z"
}