# Prediction Explanations for deployment (Serverless)

> Prediction Explanations for deployment (Serverless) - Using a specified endpoint, makes predictions
> on a given deployment and provides explanations.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-05-06T18:17:09.622817+00:00` (UTC).

## Primary page

- [Prediction Explanations for deployment (Serverless)](https://docs.datarobot.com/en/docs/api/reference/predapi/pred-ref-serverless/dep-predex.html): Full documentation for this topic (HTML).

## Sections on this page

- [Request parameters](https://docs.datarobot.com/en/docs/api/reference/predapi/pred-ref-serverless/dep-predex.html#request-parameters): In-page section heading.
- [Headers](https://docs.datarobot.com/en/docs/api/reference/predapi/pred-ref-serverless/dep-predex.html#headers): In-page section heading.
- [Query arguments (explanations specific)](https://docs.datarobot.com/en/docs/api/reference/predapi/pred-ref-serverless/dep-predex.html#query-arguments): In-page section heading.
- [Body](https://docs.datarobot.com/en/docs/api/reference/predapi/pred-ref-serverless/dep-predex.html#body): In-page section heading.
- [Response 200](https://docs.datarobot.com/en/docs/api/reference/predapi/pred-ref-serverless/dep-predex.html#response-200): In-page section heading.
- [Binary XEMP-based explanation response example](https://docs.datarobot.com/en/docs/api/reference/predapi/pred-ref-serverless/dep-predex.html#binary-prediction-example): In-page section heading.
- [Binary SHAP-based explanation response example](https://docs.datarobot.com/en/docs/api/reference/predapi/pred-ref-serverless/dep-predex.html#binary-shap-prediction-example): In-page section heading.
- ["qualitativeStrength" indicator](https://docs.datarobot.com/en/docs/api/reference/predapi/pred-ref-serverless/dep-predex.html#qualitativestrength-indicator): In-page section heading.
- [Errors List](https://docs.datarobot.com/en/docs/api/reference/predapi/pred-ref-serverless/dep-predex.html#errors-list): In-page section heading.

## Related documentation

- [Developer documentation](https://docs.datarobot.com/en/docs/api/index.html): Linked from this page.
- [API reference](https://docs.datarobot.com/en/docs/api/reference/index.html): Linked from this page.
- [Prediction API](https://docs.datarobot.com/en/docs/api/reference/predapi/index.html): Linked from this page.
- [Serverless Prediction API reference](https://docs.datarobot.com/en/docs/api/reference/predapi/pred-ref-serverless/index.html): Linked from this page.
- [Prediction Explanations](https://docs.datarobot.com/en/docs/classic-ui/modeling/analyze-models/understand/pred-explain/index.html): Linked from this page.
- [XEMP](https://docs.datarobot.com/en/docs/classic-ui/modeling/analyze-models/understand/pred-explain/xemp-pe.html): Linked from this page.
- [SHAP](https://docs.datarobot.com/en/docs/classic-ui/modeling/analyze-models/understand/pred-explain/shap-pe.html): Linked from this page.
- [XEMP calculation reference](https://docs.datarobot.com/en/docs/reference/pred-ai-ref/xemp-calc.html): Linked from this page.

## Documentation content

Endpoint: `/api/v2/deployments/<deploymentId>/predictions?maxExplanations=<number>`

Prediction Explanations identify why a given model makes a certain prediction. To calculate Prediction Explanations, use the same endpoint used for calculating bare predictions with the `maxExplanations` URI parameter set to a positive integer value. For specific calculation information, review the main [Prediction Explanations](https://docs.datarobot.com/en/docs/classic-ui/modeling/analyze-models/understand/pred-explain/index.html) documentation.

Prediction Explanations can be either:

- XEMP-based (the default). To use XEMP-based explanations, first calculate feature impact and initialize Prediction Explanations to provide aqualitative indicator (qualitativeStrength)of the effect variables have on the predictions. Explanations are computed for the top 50 features, ranked by feature impact scores (not including features with zero feature impact).
- SHAP-based. To use SHAP-based explanations, calculating feature impact is not required. ThequalitativeStrengthindicator is not available for SHAP.

> [!NOTE] Prediction Explanation considerations
> Neither XEMP or SHAP explanations are available for images (that is, no
> Image Explanations
> ).
> SHAP-based Prediction Explanations cannot be generated for multiclass projects. Only XEMP is supported for multiclass projects.
> 
> More information to consider while working with explanations can be found [here](https://docs.datarobot.com/en/docs/classic-ui/modeling/analyze-models/understand/pred-explain/index.html#feature-considerations).

> [!WARNING] Performance considerations for XEMP-based explanations
> XEMP-based explanations can be 100x slower than regular predictions. Avoid them for low-latency critical use cases. SHAP-based explanations are much faster but can add some latency too.

Request Method: `POST`

Request URL: REST API URL, for example: `https://your-company.datarobot.com/api/v2`

## Request parameters

### Headers

| Key | Description | Example(s) |
| --- | --- | --- |
| Authorization | Required; string Three methods are supported: Bearer authentication (deprecated) Basic authentication: User_email and API token (deprecated) API token | Example for Bearer authentication method: Bearer API_key-12345abcdb-xyz6789 (deprecated) Example for User_email and API token method: Basic Auth_basic-12345abcdb-xyz6789 (deprecated) Example for API token method: Token API_key-12345abcdb-xyz6789 |
| Content-Type | Optional; string type | textplain; charset=UTF-8 text/csv application/JSON multipart/form-data (For files with data, i.e., .csv, .txt files) |
| Content-Encoding | Optional; string type Currently supports only gzip-encoding with the default data extension. | gzip |

### Query arguments (explanations specific)

> [!NOTE] Note
> To trigger prediction explanations, your request must send `maxExplanations=N` where N is greater than `0`.

| Key | Type | Description | Example(s) |
| --- | --- | --- | --- |
| maxExplanations | int OR string | (Optional) Limits the number of explanations returned by server. Previously called maxCodes (deprecated). For SHAP explanations only a special constant all is also accepted. | ?maxExplanations=5?maxExplanations=all |
| thresholdLow | float | (Optional) The lower threshold for requiring a Prediction Explanation. Predictions must be below this value (or above the thresholdHigh value) for Prediction Explanations to compute. | ?thresholdLow=0.678 |
| thresholdHigh | float | (Optional) The upper threshold for requiring a Prediction Explanation. Predictions must be above this value (or below the thresholdLow value) for Prediction Explanations to compute. | ?thresholdHigh=0.345 |
| excludeAdjustedPredictions | bool | (Optional) Includes or excludes exposure-adjusted predictions in prediction responses if exposure was used during model building. The default value is true (exclude exposure-adjusted predictions). | ?excludeAdjustedPredictions=true |
| explanationNumTopClasses | int | (Optional) This argument is only for multiclass model explanations, and it is mutually exclusive with explanationClassNames. The number of top predicted classes to explain for each row. The default value is 1. | ?explanationNumTopClasses=5 |
| explanationClassNames | list of string types | (Optional) This argument is only for multiclass model explanations, and it is mutually exclusive with explanationNumTopClasses. A list of class names to explain for each row. Class names must be passed as UTF-8 bytes and must be percent-encoded (see the HTTP standard for this requirement). By default, ?explanationNumTopClasses=1 is assumed. | ?explanationClassNames=classA&explanationClassNames=classB |
| explanationAlgorithm | string | Defines the Prediction Explanation algorithm used, SHAP or XEMP. | ?explanationAlgorithm=shapexplanationAlgorithm=xemp |

The rest of the parameters like `passthroughColumns`, `passthroughColumnsSet`, and `predictionWarningEnabled` can also be used with Prediction Explanations.

### Body

| Data | Type | Example(s) |
| --- | --- | --- |
| Data to predict | raw text form-data | PassengerId,Pclass,Name,Sex,Age,SibSp,Parch,Ticket,Fare,Cabin,Embarked 892,3,"Kelly, Mr. James",male,34.5,0,0,330911,7.8292,,Q 893,3,"Wilkes, Mrs. James (Ellen Needs)",female,47,1,0,363272,7,,S 894,2,"Myles, Mr. Thomas Francis",male,62,0,0,240276,9.6875,,Q Key: file, value: file_with_data_to_predict.csv |

### Response 200

#### Binary XEMP-based explanation response example

```
{
    "data": [
        {
            "predictionValues": [
                {
                    "value": 0.07836511,
                    "label": 1
                },
                {
                    "value": 0.92163489,
                    "label": 0
                }
            ],
            "predictionThreshold": 0.5,
            "prediction": 0,
            "rowId": 0,
            "predictionExplanations": [
                {
                    "featureValue": "male",
                    "strength": -0.6706725349,
                    "feature": "Sex",
                    "qualitativeStrength": "---",
                    "label": 1
                },
                {
                    "featureValue": 62,
                    "strength": -0.6325465255,
                    "feature": "Age",
                    "qualitativeStrength": "---",
                    "label": 1
                },
                {
                    "featureValue": 9.6875,
                    "strength": -0.353000328,
                    "feature": "Fare",
                    "qualitativeStrength": "--",
                    "label": 1
                }
            ]
        }
    ]
}
```

#### Binary SHAP-based explanation response example

```
{
   "data":[
      {
         "deploymentApprovalStatus": "APPROVED",
         "prediction": 0.0,
         "predictionExplanations": [
            {
               "featureValue": "9",
               "strength": 0.0534648234,
               "qualitativeStrength": null,
               "feature": "number_diagnoses",
               "label": 1
            },
            {
               "featureValue": "0",
               "strength": -0.0490243586,
               "qualitativeStrength": null,
               "feature": "number_inpatient",
               "label": 1
            }
         ],
         "rowId": 0,
         "predictionValues": [
            {
               "value": 0.3111782477,
               "label": 1
            },
            {
               "value": 0.6888217523,
               "label": 0.0
            }
         ],
         "predictionThreshold": 0.5,
         "shapExplanationsMetadata": {
            "warnings": null,
            "remainingTotal": -0.089668474,
            "baseValue": 0.3964062631
         }
      }
   ]
}
```

### "qualitativeStrength" indicator

The "qualitativeStrength" indicates the effect of the feature's value on predictions, based on XEMP calculations. The following table provides an example for a model with two features. See the [XEMP calculation reference](https://docs.datarobot.com/en/docs/reference/pred-ai-ref/xemp-calc.html) for full calculation details.

> [!NOTE] Note
> This response is an XEMP-only feature.

| Indicator... | Description |
| --- | --- |
| +++ | Absolute score is > 0.75 and feature has positive impact. |
| --- | Absolute score is > 0.75 and feature has negative impact. |
| ++ | Absolute score is between (0.25, 0.75) and feature has positive impact. |
| -- | Absolute score is between (0.25, 0.75) and feature has negative impact. |
| + | Absolute score is between (0.001, 0.25) and feature has positive impact. |
| - | Absolute score is between (0.001, 0.25) and feature has negative impact. |
| <+ | Absolute score is between (0, 0.001) and feature has positive impact. |
| <- | Absolute score is between (0, 0.001) and feature has negative impact. |

## Errors List

| HTTP Code | Sample error message | Reason(s) |
| --- | --- | --- |
| 404 NOT FOUND | {"message": "Not found"} | Provided an invalid :deploymentId (deleted deployment). |
| 404 NOT FOUND | {"message": "Bad request"} | Provided the wrong format for :deploymentId. |
| 422 UNPROCESSABLE ENTITY | {"message": "{'max_codes': DataError(value can't be converted to int)}"} | Provided maxCodes parameter in unsupported data type (i.e., non-integer values). |
| 422 UNPROCESSABLE ENTITY | {"message": "{'threshold_high': DataError(value can't be converted to float)}"} | Provided threshold_high parameter in unsupported data type (i.e., non-integer values). |
| 422 UNPROCESSABLE ENTITY | {"message": "{'threshold_low': DataError(value can't be converted to float)}"} | Provided threshold_low parameter in unsupported data type (i.e., non-integer values). |
| 422 UNPROCESSABLE ENTITY | {"message": "Multiclass models cannot be used for Prediction Explanations"} | Provided a multiclass classification problem dataset, which is not supported for this endpoint. |
| 422 UNPROCESSABLE ENTITY | {"message": "This endpoint does not support predictions on time series models. Please use the timeSeriesPredictions route instead."} | Provided the deploymentId of a time series project, which is not supported for this endpoint. |
| 422 UNPROCESSABLE ENTITY | {"message": "{'exclude\_adjusted\_predictions': DataError(value can't be converted to Bool)}"} | Sent an empty or non-Boolean value with the excludeAdjustedPredictions parameter. |
| 422 UNPROCESSABLE ENTITY | {"message": "'predictionWarningEnabled': value can't be converted to Bool"} | Provided an invalid (non-boolean) value for predictionWarningEnabled parameter. |