Predict

POST/v1/predict

Score one or more rows against a deployed model. Works for both v1 and v2 deployments. Every prediction can include an additive explanation breakdown showing exactly how each feature contributed to the score.

Query parameters

thresholdfloatdefault: 0.5

Classification decision threshold, applied to the calibrated probability. Ignored for regression.

show_breakdownbooldefault: true

Include the per-feature explanation breakdown for each row. Set to false to slim the response payload.

fill_missingbooldefault: false

Fill any missing model features with NaN instead of rejecting the request.

Request body

A JSON array of row objects. Each row maps feature names to values and must cover the model's input features (unless fill_missing=true):

[
  {
    "tenure_days": 420,
    "avg_order_value": 86.5,
    "discount_applied": 0.1,
    "plan": "premium"
  },
  {
    "tenure_days": 31,
    "avg_order_value": 22.0,
    "discount_applied": 0.0,
    "plan": "basic"
  }
]

If a preprocessing pipeline is attached to the deployment, it runs automatically before scoring — send rows in the shape of your raw source data.

Response

An array with one result object per input row, in the same order.

Classification:

[
  {
    "index": 0,
    "id": null,
    "partition": "__dataset__",
    "score": 1.24,
    "proba": 0.78,
    "pred": 1,
    "support": 0.0,
    "breakdown": [
      { "feature": "base_value", "value": null, "score": -0.20 },
      { "feature": "tenure_days", "value": "420", "score": 0.85 },
      { "feature": "avg_order_value", "value": "86.5", "score": 0.42 },
      { "feature": "plan", "value": "premium", "score": 0.17 }
    ]
  }
]

Regression:

[
  {
    "index": 0,
    "id": null,
    "partition": "__dataset__",
    "score": 231.4,
    "pred": 231.4,
    "breakdown": [
      { "feature": "base_value", "value": null, "score": 180.0 },
      { "feature": "tenure_days", "value": "420", "score": 40.1 },
      { "feature": "avg_order_value", "value": "86.5", "score": 11.3 }
    ]
  }
]

Fields

Field	Type	Description
index	int	Position of the row in the request array
id	string | null	Composite row ID when the model has ID columns configured; otherwise null
partition	string	Partition the row was scored against (__dataset__ for non-partitioned models)
score	float	Classification: the link-scale (logit) score the breakdown sums to. Regression: the raw-unit prediction (equals pred)
proba	float	Classification only. Calibrated probability in [0, 1]
pred	int | string | float	The decision. Classification: class label from thresholding proba >= threshold. Regression: the numeric prediction
support	float	Classification only. Support metric for the score (0.0 on v2 models)
breakdown	array | null	Additive per-feature contributions — see Explainability. null when show_breakdown=false

Example

curl -X POST "https://inference.xplainable.io/v1/predict?threshold=0.5" \
  -H "api_key: YOUR_DEPLOY_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"tenure_days": 420, "avg_order_value": 86.5, "discount_applied": 0.1, "plan": "premium"}]'

import requests

response = requests.post(
    "https://inference.xplainable.io/v1/predict",
    headers={"api_key": DEPLOY_KEY},
    json=[{
        "tenure_days": 420,
        "avg_order_value": 86.5,
        "discount_applied": 0.1,
        "plan": "premium",
    }],
)
for row in response.json():
    print(row["pred"], row["proba"])

Batching

The request body is an array — send many rows in one call rather than one call per row. Usage is metered per row scored, not per request, so batching is free and much faster.

Try it

Edit the row and send — the response is the real per-row schema, breakdown included:

TRY ITsandbox — real model, precomputed

POSThttps://inference.xplainable.io/v1/predict?threshold=0.5

API_KEY HEADER

[ { "tenure_days": 381, "avg_order_value": 84, "discount_applied": 0.1, "plan": "premium" } ]

Send a request to see the response — the body is a JSON array of rows

Inputs snap to the demo grid; numeric values are matched to the nearest level and unknown categories fall back to the first. Against a live deployment the same request shape returns exact values for any input.

Scoring without a deployment

To score rows against a trained model without deploying it (e.g. during evaluation), use the platform SDK instead — it routes through the platform API with your account key:

result = client.workflow.predict(
    model_id=model_id,
    rows=[{"tenure_days": 420, "avg_order_value": 86.5}],
)