Predictions

Predictions

Log the predictions your models make, or read back the ones Kaimei made, for explanation and monitoring.

A prediction is one input and the output a model produced for it. Log the predictions your own stack makes so they can be explained later and monitored for drift, or let Kaimei make them with POST /v1/models/{model}/predict.

#The Prediction object

The output is stored as you sent it: an object is kept as is, a number becomes {"value": n}, a string becomes {"label": s}, a boolean becomes a label and a value, a list becomes {"raw": [...]}. Predictions Kaimei makes carry the normalised output shown under predict.

Attributes

idstring
pred_ identifier, or the prediction_id you supplied (up to 40 characters).
model_idstring

inputobject

The feature row as sent. Image pixels are stored packed and read back as the same lists.

outputobject | null

See above.

latency_msnumber | null

Your model's latency, if you logged it; Kaimei's own when it predicted.

sourcestring
api, sdk (the Python client), or kaimei (made by Kaimei, through predict or when an explanation ran with log_prediction).
metadataobject

Yours.

actualobject | null

What really happened, once you attach it: {"label": "decline"} for a classifier, {"value": 3.2} for a regression. null until then.

actual_attimestamp | null

When the outcome was recorded.

created_attimestamp

The timestamp you sent, or the time of logging.

The Prediction object
{
  "object": "prediction",
  "id": "pred_8f2a19",
  "model_id": "mdl_390bd6d9568f626851ef",
  "input": {
    "income": 72000,
    "credit_score": 681,
    "utilization": 0.41,
    "debt_to_income": 0.38,
    "loan_amount": 18000,
    "employment_years": 4,
    "num_delinquencies": 1,
    "age": 34,
    "home_ownership": "rent"
  },
  "output": {"label": "decline", "probability": 0.81},
  "latency_ms": 12.4,
  "source": "api",
  "metadata": {"request_id": "req_01HZX"},
  "actual": null,
  "actual_at": null,
  "created_at": "2026-10-31T22:40:23.260448Z"
}

#Log a prediction

POST/v1/predictionsAPI key or session

Record one prediction your model made. Counts against the monthly predictions quota and the 600-per-hour limit.

Body parameters

modelstringrequired

Model id or slug.

inputobjectrequired

The feature row.

outputanyoptional

What the model returned: an object, a number, a string label, a boolean or a list.

prediction_idstringoptional

Your own id for the record, up to 40 characters and unique inside this workspace. Another workspace may use the same id. One already used here is 409 prediction_id_in_use. Defaults to a generated pred_ id.

latency_msnumberoptional

Your model's latency.

timestamptimestampoptional

When the prediction happened, for backfills. Defaults to now.

metadataobjectoptional

Free-form.

actualanyoptional

The real outcome, when you already know it (a backfill). Same forms as attaching outcomes; an outcome the model can't have is 422 invalid_actual.

Returns

The Prediction. 201.
client.predictions.create(
    model="credit-risk-v3",
    input=row,
    output={"label": "decline", "probability": 0.81},
    prediction_id="pred_8f2a19",
    latency_ms=12.4,
    metadata={"request_id": "req_01HZX"},
)
curl -X POST https://api.kaimei.ai/v1/predictions \
  -H "Authorization: Bearer $KAIMEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "credit-risk-v3", "prediction_id": "pred_8f2a19", "latency_ms": 12.4,
   "input": {"income": 72000, "credit_score": 681, "utilization": 0.41, "debt_to_income": 0.38, "loan_amount": 18000,
             "employment_years": 4, "num_delinquencies": 1, "age": 34, "home_ownership": "rent"},
   "output": {"label": "decline", "probability": 0.81}, "metadata": {"request_id": "req_01HZX"}}'
201 CreatedResponse
{
  "object": "prediction",
  "id": "pred_8f2a19",
  "model_id": "mdl_390bd6d9568f626851ef",
  "input": {
    "income": 72000,
    "credit_score": 681,
    "utilization": 0.41,
    "debt_to_income": 0.38,
    "loan_amount": 18000,
    "employment_years": 4,
    "num_delinquencies": 1,
    "age": 34,
    "home_ownership": "rent"
  },
  "output": {"label": "decline", "probability": 0.81},
  "latency_ms": 12.4,
  "source": "api",
  "metadata": {"request_id": "req_01HZX"},
  "actual": null,
  "actual_at": null,
  "created_at": "2026-10-31T22:40:23.260448Z"
}

#Log many predictions

POST/v1/predictions/batchAPI key or session

Record up to 1,000 predictions in one request. Each item takes the same fields as a single prediction except model. The quota is checked once for the whole batch and the rate limit counts one hit.

Body parameters

modelstringrequired

Model id or slug.

itemsarrayrequired

1 to 1,000 items of {input, output?, prediction_id?, latency_ms?, timestamp?, metadata?, actual?}.

Returns

{"object": "list", "data": [...predictions], "count": n}.
client.predictions.create_batch(model="credit-risk-v3", items=[
    {"prediction_id": "pred_8f2a1a", "input": {**row, "income": 54000}, "output": 0.63},
    {"prediction_id": "pred_8f2a1b", "input": {**row, "credit_score": 790, "utilization": 0.08},
     "output": {"label": "approve", "probability": 0.91}},
])
curl -X POST https://api.kaimei.ai/v1/predictions/batch \
  -H "Authorization: Bearer $KAIMEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "credit-risk-v3", "items": [
     {"prediction_id": "pred_8f2a1a", "input": {"income": 54000, "credit_score": 681, "utilization": 0.41}, "output": 0.63},
     {"prediction_id": "pred_8f2a1b", "input": {"income": 72000, "credit_score": 790, "utilization": 0.08},
      "output": {"label": "approve", "probability": 0.91}}
   ]}'
200 OKResponse
{
  "object": "list",
  "data": [
    {
      "object": "prediction",
      "id": "pred_8f2a1a",
      "model_id": "mdl_390bd6d9568f626851ef",
      "input": {
        "income": 54000,
        "credit_score": 681,
        "utilization": 0.41,
        "debt_to_income": 0.38,
        "loan_amount": 18000,
        "employment_years": 4,
        "num_delinquencies": 1,
        "age": 34,
        "home_ownership": "rent"
      },
      "output": {"value": 0.63},
      "latency_ms": null,
      "source": "api",
      "metadata": {},
      "actual": null,
      "actual_at": null,
      "created_at": "2026-10-31T22:40:23.268794Z"
    },
    {
      "object": "prediction",
      "id": "pred_8f2a1b",
      "model_id": "mdl_390bd6d9568f626851ef",
      "input": {
        "income": 72000,
        "credit_score": 790,
        "utilization": 0.08,
        "debt_to_income": 0.38,
        "loan_amount": 18000,
        "employment_years": 4,
        "num_delinquencies": 1,
        "age": 34,
        "home_ownership": "rent"
      },
      "output": {"label": "approve", "probability": 0.91},
      "latency_ms": null,
      "source": "api",
      "metadata": {},
      "actual": null,
      "actual_at": null,
      "created_at": "2026-10-31T22:40:23.268794Z"
    }
  ],
  "count": 2
}

#Attach outcomes

POST/v1/predictions/actualsAPI key or session

Record what really happened for up to 1,000 logged predictions: the loan that defaulted, the claim that was fraud, the demand that came in. Outcomes usually arrive days or months after the prediction; once they do, performance and the performance analysis measure the model against them. Every outcome is checked before any is written, so one bad outcome leaves the whole batch unwritten. Sending an outcome again replaces it. Counts against the 600-per-hour predictions limit as one hit, not against the monthly quota.

Body parameters

modelstringoptional

Model id or slug. When set, predictions of other models are reported as not found.

itemsarrayrequired

1 to 1,000 items of {prediction_id, actual}. Each prediction_id may appear once.

prediction_idstringrequired

The prediction's id: the pred_ id Kaimei returned or the one you supplied.

actualanyrequired

For a classifier, the class name ("decline", case-insensitive), its position in outputs.labels (1), or true / false for a binary model (the positive class, the last label, is true). For a regression, a number. null clears the outcome.

Returns

{"object": "actuals", "updated": n, "cleared": n, "not_found": [ids]}. An outcome the model can't have is 422 invalid_actual naming the item (param: "items.3.actual"); a repeated id is 422 duplicate_prediction_id.
client.predictions.log_actual("pred_8f2a19", "decline")

# many at once: a dict, a list of {"prediction_id", "actual"}, or a pandas Series indexed by id.
# Any number; the client sends 1,000 per request. NaN is skipped.
result = client.predictions.log_actuals({"pred_8f2a19": "decline", "pred_8f2a1a": "approve"},
                                        model="credit-risk-v3")
print(result.updated, result.not_found)

# or when the prediction is logged, for a backfill
client.predictions.create(model="credit-risk-v3", input=row, output=0.81, actual="decline")
curl -X POST https://api.kaimei.ai/v1/predictions/actuals \
  -H "Authorization: Bearer $KAIMEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "credit-risk-v3", "items": [
     {"prediction_id": "pred_8f2a19", "actual": "decline"},
     {"prediction_id": "pred_nope", "actual": "approve"}
   ]}'
200 OKResponse
{
  "object": "actuals",
  "updated": 1,
  "cleared": 0,
  "not_found": ["pred_nope"]
}

#List predictions

GET/v1/predictionsAPI key or session

Predictions in your organization, newest first.

Query parameters

modelstringoptional

Model id or slug.

sourcestringoptional
api, sdk or kaimei.
has_actualbooleanoptional

Only predictions with (true) or without (false) an outcome: the second is the list still waiting for one.

limitintegeroptionaldefault 50

1 to 500.

offsetintegeroptionaldefault 0

Returns

A page of Predictions.
page = client.predictions.list(model="credit-risk-v3", source="api", limit=100)
for prediction in client.predictions.iterate(model="credit-risk-v3"):
    ...
curl "https://api.kaimei.ai/v1/predictions?model=credit-risk-v3&limit=2" \
  -H "Authorization: Bearer $KAIMEI_API_KEY"
200 OKResponse
{
  "object": "list",
  "data": [
    {
      "object": "prediction",
      "id": "pred_8f2a1b",
      "model_id": "mdl_390bd6d9568f626851ef",
      "input": …,
      "output": {"label": "approve", "probability": 0.91},
      "latency_ms": null,
      "source": "api",
      "metadata": {},
      "actual": null,
      "actual_at": null,
      "created_at": "2026-10-31T22:40:23.260448Z"
    },
    {
      "object": "prediction",
      "id": "pred_8f2a19",
      "model_id": "mdl_390bd6d9568f626851ef",
      "input": …,
      "output": {"label": "decline", "probability": 0.81},
      "latency_ms": 12.4,
      "source": "api",
      "metadata": {"request_id": "req_01HZX"},
      "actual": null,
      "actual_at": null,
      "created_at": "2026-10-31T22:40:23.260448Z"
    }
  ],
  "total": 196,
  "limit": 2,
  "offset": 0,
  "has_more": true
}

#Retrieve a prediction

GET/v1/predictions/{prediction_id}API key or session

One prediction by id, including an id you supplied yourself.

Path parameters

prediction_idstringrequired

Returns

A Prediction.
prediction = client.predictions.retrieve("pred_8f2a19")
curl https://api.kaimei.ai/v1/predictions/pred_8f2a19 \
  -H "Authorization: Bearer $KAIMEI_API_KEY"
200 OKResponse
{
  "object": "prediction",
  "id": "pred_8f2a19",
  "model_id": "mdl_390bd6d9568f626851ef",
  "input": {
    "income": 72000,
    "credit_score": 681,
    "utilization": 0.41,
    "debt_to_income": 0.38,
    "loan_amount": 18000,
    "employment_years": 4,
    "num_delinquencies": 1,
    "age": 34,
    "home_ownership": "rent"
  },
  "output": {"label": "decline", "probability": 0.81},
  "latency_ms": 12.4,
  "source": "api",
  "metadata": {"request_id": "req_01HZX"},
  "actual": null,
  "actual_at": null,
  "created_at": "2026-10-31T22:40:23.260448Z"
}