Skip to content

On-premise users: click in-app to access the full platform documentation for your version of DataRobot.

Predictions for deployments

Using the endpoint below, you can provide the data necessary to calculate predictions for a specific deployment. If you need to make predictions for an unstructured custom inference model, see Predictions for unstructured model 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 A per-organization secret used as an additional authentication factor for prediction servers. Retrieve a datarobot-key programmatically by accessing the /api/v2/predictionServers/ endpoint. The endpoint returns a URL to a prediction server and a corresponding datarobot-key

Required for Self-Managed AI Platform 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
  • text/plain; 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
Accept Optional; string type

Controls the shape of the response schema. Currently JSON(default) and CSV are supported. See examples.
  • application/json (default)
  • text/csv (for CSV output)

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

Query arguments

Key Type Description Example(s)
passthroughColumns list of strings (Optional) Controls which columns from a scoring dataset to expose (or 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 be percent-encoded (see the HTTP standard for this requirement). Make sure to use the exact name of a column as a value.
/v1.0/deployments/<deploymentId>/predictions?passthroughColumns=colA&passthroughColumns=colB
passthroughColumnsSet string (Optional) 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 bool (Optional) DataRobot monitors unusual or anomalous predictions in real-time and indicates when they are detected.

If this argument is set to true, a new key is added to each prediction to specify 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 } ] }
decimalsNumber integer (Optional) Configures the float precision in prediction results by setting the number of digits after the decimal point.

If there aren't any digits after the decimal point, rather than adding zeros, the float precision is less than the value set by decimalsNumber.
?decimalsNumber=15

Note

The passthroughColumns and passthroughColumnsSet parameters are mutually exclusive and cannot both be passed in the same request. Also, while there isn't a limit on the number of column names you can pass with the passthroughColumns query parameter, there is a limit on the size of the HTTP request line (currently 8192 bytes).

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 UI (the Deploy tab), 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 February 16, 2024