Skip to content

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

Predictions for deployments

Endpoint: /deployments/<deploymentId>/predictions

Calculates predictions based on user-provided data for a specific deployment. Note that this endpoint works only for deployed models.

Note

You can find the deployment ID in the sample code output of the Deployments > Predictions > Prediction API tab (with Interface set to "API Client")

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 the DataRobot API:
GET <URL>/api/v2/modelDeployments/<deploymentId>

Additional parameters

Key Description Example(s)
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/predictions?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/predictions?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

Binary prediction

Label: For regression and binary classification tasks, DataRobot API always returns 1 for the positive class and 0 for the negative class. Although the actual values for the classes may be different depending on the data provided (like "yes"/"no"), the DataRobot API will always return 1/0. For multiclass classification, the DataRobot API returns the value itself.

Value: Shows the probability of an event happening (where 0 and 1 are min and max probability, respectively). The user can adjust the threshold that links the value with the prediction label.

PredictionThreshold (Applicable to binary classification projects only): Threshold is the point that sets the class boundary for a predicted value. The model classifies an observation below the threshold as FALSE, and an observation above the threshold as TRUE. In other words, DataRobot automatically assigns the positive class label to any prediction exceeding the threshold. This can be configured manually through the (Deploy tab) UI page, or through the DataRobot API (i.e., the PATCH /api/v2/projects/(projectId)/models/(modelId) route).

The actual response is dependent on the classification task: binary classification, regression or multiclass task.

Binary classification example

{
    "data": [
        {
            "predictionValues": [
                {
                    "value": 0.2789450715,
                    "label": 1
                },
                {
                    "value": 0.7210549285,
                    "label": 0
                }
            ],
            "predictionThreshold": 0.5,
            "prediction": 0,
            "rowId": 0
        }
    ]
}

Regression prediction example

{
  "data": [
    {
      "predictionValues": [
        {
          "value": 6754486.5,
          "label": "revenue"
        }
      ],
      "prediction": 6754486.5,
      "rowId": 0
    }
  ]
}

Multiclass classification prediction example

{
    "data": [
        {
            "predictionValues": [
                {
                    "value": 0.9999997616,
                    "label": "setosa"
                },
                {
                    "value": 2.433e-7,
                    "label": "versicolor"
                },
                {
                    "value": 1.997631915e-16,
                    "label": "virginica"
                }
            ],
            "prediction": "setosa",
            "rowId": 0
        }
    ]
}

Errors List

HTTP Code Sample error message Reason(s)
400 BAD REQUEST {"message": "Bad request"} Added external deployments that are unsupported.
404 NOT FOUND {"message": "Deployment :deploymentId cannot be found for user :userId"} Provided an invalid :deploymentId (deleted deployment).

Updated November 16, 2021
Back to top