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
pred_ identifier, or the prediction_id you supplied (up to 40 characters).The feature row as sent. Image pixels are stored packed and read back as the same lists.
See above.
Your model's latency, if you logged it; Kaimei's own when it predicted.
api, sdk (the Python client), or kaimei (made by Kaimei, through predict or when an explanation ran with log_prediction).Yours.
What really happened, once you attach it: {"label": "decline"} for a classifier, {"value": 3.2} for a regression. null until then.
When the outcome was recorded.
The timestamp you sent, or the time of logging.
{
"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
/v1/predictionsAPI key or sessionRecord one prediction your model made. Counts against the monthly predictions quota and the 600-per-hour limit.
Body parameters
Model id or slug.
The feature row.
What the model returned: an object, a number, a string label, a boolean or a list.
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.
Your model's latency.
When the prediction happened, for backfills. Defaults to now.
Free-form.
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
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"}}'{
"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
/v1/predictions/batchAPI key or sessionRecord 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
Model id or slug.
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}}
]}'{
"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
/v1/predictions/actualsAPI key or sessionRecord 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
Model id or slug. When set, predictions of other models are reported as not found.
1 to 1,000 items of {prediction_id, actual}. Each prediction_id may appear once.
The prediction's id: the pred_ id Kaimei returned or the one you supplied.
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"}
]}'{
"object": "actuals",
"updated": 1,
"cleared": 0,
"not_found": ["pred_nope"]
}#List predictions
/v1/predictionsAPI key or sessionPredictions in your organization, newest first.
Query parameters
Model id or slug.
api, sdk or kaimei.Only predictions with (true) or without (false) an outcome: the second is the list still waiting for one.
1 to 500.
Returns
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"{
"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
/v1/predictions/{prediction_id}API key or sessionOne prediction by id, including an id you supplied yourself.
Path parameters
Returns
prediction = client.predictions.retrieve("pred_8f2a19")curl https://api.kaimei.ai/v1/predictions/pred_8f2a19 \
-H "Authorization: Bearer $KAIMEI_API_KEY"{
"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"
}