Analyses

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

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

type	Runs	Produces
`full`	Every step below, in order	Seven insights
`global_importance`	Permutation importance over the population; with labels, also the drop in accuracy or R².	`global_importance`
`partial_dependence`	Importance first, then behaviour (partial dependence and individual) curves for the `top_features` most important features.	`global_importance`, `partial_dependence`
`interactions`	Importance first, then pairwise non-additivity among the top features.	`global_importance`, `interactions`
`robustness`	Outputs and decisions under `epsilon`-σ input noise.	`robustness`
`drift`	Reference rows vs the latest `window` logged predictions, by PSI.	`drift`
`learned_rules`	Importance and curves first, then one plain-English rule per feature.	`global_importance`, `partial_dependence`, `learned_rules`
`behavior`	Distribution of the outputs over the population.	`behavior`

Image models run only global_importance (patch occlusion), behavior and drift; 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.

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.

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, 20 to 10000.

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"
}