---
title: Prediction Explanations for deployment
description: Using a specified endpoint, makes predictions on a given deployment and provides explanations.

---

# Prediction Explanations for deployments {: #prediction-explanations-for-deployments }

**Endpoint:** `/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.

Prediction Explanations can be either:

* [XEMP](xemp-pe)-based (the default). To use XEMP-based explanations, first calculate feature impact and initialize Prediction Explanations to provide a [qualitative indicator (qualitativeStrength)](#qualitativestrength-indicator) 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](shap-pe)-based if the [**Include only models with SHAP value support**](additional) advanced option is enabled prior to model building. Calculating feature impact is not required; note that the [qualitativeStrength](#qualitativestrength-indicator) indicator is not available for SHAP.

XEMP- and SHAP-based explanations are mutually exclusive&mdash;a model cannot have both XEMP and SHAP explanations. See the [Prediction Explanations](pred-explain/index) full documentation for specific calculation information.

Note the following:

* SHAP-based explanations are not available for time series or custom models.
* Neither XEMP or SHAP explanations are available for images (that is, no [Image Explanations](xemp-pe#prediction-explanations-for-visual-ai)).

!!! 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.

!!! note "Multiclass support"
    Prediction Explanations cannot be generated for XEMP- or SHAP-based multiclass projects.
    More information to consider while working with explanations can be found [here](pred-explain/index#feature-considerations).

**Request Method:** `POST`

**Request URL:** deployed URL, for example: `https://your-company.orm.datarobot.com/predApi/v1.0`

##  Request parameters {: #request-parameters }

###  Headers {: #headers }

| Key | Description |Example(s) |
|------------------|---------------------|------------------|
| Datarobot-key | A per-organization secret used as an additional authentication factor for prediction servers. Retrieve a datarobot-key pragmatically by accessing the `/api/v2/predictionServers` endpoint. The endpoint returns a URL to a prediction server and a corresponding datarobot-key. <br><br> Required for Self-Managed AI Platform users; string type  <br><br> Once a model is deployed, see the code snippet in the DataRobot UI, [Predictions > Prediction API](code-py). | `DR-key-12345abcdb-xyz6789`|
| Authorization    | Required; string <br><br> Three methods are supported:    <ul><li> Bearer authentication  </li><li> (deprecated) Basic authentication: User_email and API token  </li><li> (deprecated) API token | <ul><li> Example for Bearer authentication method: `Bearer API_key-12345abcdb-xyz6789`  </li><li> (deprecated) Example for User_email and API token method: `Basic Auth_basic-12345abcdb-xyz6789`  </li><li> (deprecated) Example for API token method: `Token API_key-12345abcdb-xyz6789` |
| Content-Type     | Optional; string type | <ul><li> textplain; charset=UTF-8  </li><li> text/csv  </li><li> application/JSON  </li><li> multipart/form-data (For files with data, i.e., .csv, .txt files) |
| Content-Encoding | Optional; string type <br><br> Currently supports only gzip-encoding with the default data extension. | gzip |


**Datarobot-key:** This header is required only with the managed AI Platform. It is used as a precaution to secure user data from other verified DataRobot users. The key can also be retrieved with the following request to DataRobot API: <br>`GET <URL>/api/v2/modelDeployments/<deploymentId>`

###  Query arguments (explanations specific) {: #query-arguments }

!!! 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. | <ul><li>`?maxExplanations=5`</li><li>`?maxExplanations=all`</li></ul> |
| 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`. <br><br> 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`. <br><br> 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](https://tools.ietf.org/html/rfc2616){ target=_blank } for this requirement). By default, `explanationNumTopClasses=1` is assumed. | `?explanationClassNames=classA&explanationClassNames=classB` |

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


###  Body {: #body }

| Data | Type | Example(s) |
|---|---------|------------------|
| Data to predict  | <ul><li> raw text  </li><li> form-data     |   <ul><li> 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  </li><li> Key: file, value: file_with_data_to_predict.csv |


###  Response 200 {: #response-200 }



#### Binary XEMP-based explanation response example {: #binary-prediction-example }

```json
{
    "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 {: #binary-shap-prediction-example }

```json
{
   "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 {: #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](xemp-calc) for full calculation details.

!!! 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 {: #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. |
