Skip to content

Click in-app to access the full platform documentation for your version of DataRobot.

Prediction Explanations for deployments

Endpoint: /deployments/<deploymentId>/predictionExplanations

Makes predictions on a given deployment and provides explanations. To use this endpoint, you must have calculated the feature impact and initialized Prediction Explanations, which provide a qualitative indicator of the effect variables have on the predictions. (Prediction Explanations identify why a given model made a certain prediction.)

Note

Prediction Explanations cannot be generated for multiclass projects.

Request Method: POST

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

Request parameters

Headers

Key Description Example(s)
Datarobot-key Required for Managed AI Cloud users; string type

Once a model is deployed, see the code snippet in the DataRobot UI, Predictions > Prediction API.
DR-key-12345abcdb-xyz6789
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

Datarobot-key: This header is required only with Managed AI Cloud. 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:
GET <URL>/api/v2/modelDeployments/<deploymentId>

Additional parameters

Key Description Example(s)
maxExplanations Optional; integer type

Limits the number of explanations returned by server. Previously called maxCodes.
?maxExplanations=5
thresholdHigh Optional; number type

The prediction explanation high threshold. Predictions must be above this value (or below the 'thresholdLow' value) to have PredictionExplanations computed.
?thresholdHigh=0.805
thresholdLow Optional; number type

The prediction explanation low threshold. Predictions must be below this value (or above the 'thresholdHigh' value) to have PredictionExplanations computed.
?thresholdLow=0.1396484375
excludeAdjustedPredictions Optional; string type

If True (the default), adjusted predictions are included in the PredictionExplanationsSample response.
?excludeAdjustedPredictions=false
passthroughColumns Optional; string type

Controls which columns from a scoring dataset to expose (or to copy over) in a prediction response.

The request may contain zero, one, or more columns. (There’s no limit on how many column names you can pass.) Column names must be passed as UTF-8 bytes and must be percent-encoded (see the HTTP standard on this requirement). Make sure to use the actual name of a column as a value.
/v1.0/deployments/:deploymentId/predictionExplanations?passthroughColumns=colA&passthroughColumns=colB
passthroughColumnsSet Optional; string type

Controls which columns from a scoring dataset to expose (or to copy over) in a prediction response. The only possible option is “all” and, if passed, all columns from a scoring dataset are exposed.
/v1.0/deployments/:deploymentId/predictionExplanations?passthroughColumnsSet=all
predictionWarningEnabled Optional; bool type

If enabled, DataRobot monitors any unusual or anomalous predictions in real-time and indicates when they are detected.

If set to true, a new key is added to each prediction that specifies the result of the Humility check. Otherwise, there are no changes in the prediction response.
/v1.0/deployments/deploymentId/predictions?predictionWarningEnabled=true

Response:

{ "data": [ { "predictionValues": [ { "value": 18.6948852, "label": "y" } ], "isOutlierPrediction": false, "rowId": 0, "prediction": 18.6948852 } ] }

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

The "qualitativeStrength" indicates how important the feature was when making the current predictions, based on feature impact calculations. (See more information here.)

"qualitativeStrength" indicator

This indicator... Means...
+++ 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.

Binary prediction 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
                }
            ]
        }
    ]
}

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.

Updated September 2, 2021
Back to top