Skip to content

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

Time series predictions for deployments

Endpoint: /deployments/<deploymentId>/predictions

Makes time series predictions for a deployed model.

Request Method: POST

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

Request parameters

Headers

Key Type Description Example(s)
Datarobot-key string 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
33257d41-fcc9-7c01-161c-3467df169a50
Authorization 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

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 (time series models only)

Key Type Description Example(s)
forecastPoint ISO-8601 string An ISO 8601 formatted DateTime string, without timezone, representing the forecast point. This parameter cannot be used if predictionsStartDate and predictionsEndDate are passed. ?forecastPoint=2013-12-20T01:30:00Z
relaxKnownInAdvanceFeaturesCheck bool true or false. When true, missing values for known-in-advance features are allowed in the forecast window at prediction time. The default value is false. Note that the absence of known-in-advance values can negatively impact prediction quality. ?relaxKnownInAdvanceFeaturesCheck=true
predictionsStartDate ISO-8601 string The time in the dataset when bulk predictions begin generating. This parameter must be defined together with predictionsEndDate. The forecastPoint parameter cannot be used if predictionsStartDate and predictionsEndDate are passed. ?predictionsStartDate=2013-12-20T01:30:00Z&predictionsEndDate=2013-12-20T01:40:00Z
predictionsEndDate ISO-8601 string The time in the dataset when bulk predictions stop generating. This parameter must be defined together with predictionsStartDate. The forecastPoint parameter cannot be used if predictionsStartDate and predictionsEndDate are passed. See above.

It is possible to use standard URI parameters, including passthroughColumns, passthroughColumnsSet, and maxExplanations.

XEMP-based explanations support

Time series supports XEMP explanations. See Prediction Explanations for examples of the maxExplanations URI parameter.

Body

Data Type Example(s)
Historic and prediction data JSON Raw data shown in image below.

Response 200

Regression prediction example

{
  "data": [
    {
      "seriesId": null,
      "forecastPoint": "2013-12-20T00:00:00Z",
      "rowId": 35,
      "timestamp": "2013-12-21T00:00:00.000000Z",
      "predictionValues": [
        {
        "value": 2.3353628422,
        "label": "sales (actual)"
        }
    ],
    "forecastDistance": 1,
    "prediction": 2.3353628422
    }
  ]
}

Binary classification prediction example

{
  "data": [
    {
      "rowId": 147,
      "prediction": "low",
      "predictionThreshold": 0.5,
      "predictionValues": [
        {"label": "low", "value": 0.5158823954},
        {"label": "high", "value": 0.4841176046},
      ],
      "timestamp": "1961-04-01T00:00:00.000000Z",
      "forecastDistance": 2,
      "forecastPoint": "1961-02-01T00:00:00Z",
      "seriesId": null,
    }
  ]
}

Errors List

HTTP Code Sample error message Reason(s)
400 BAD REQUEST {"message": "Based on the forecast point (10/26/08), there are no rows to predict that fall inside of the forecast window (10/27/08 to 11/02/08). Try adjusting the forecast point to an earlier date or appending new future rows to the data."} No empty rows were provided to predict on.
400 BAD REQUEST {"message": "No valid output rows"} No historic information was provided; there's only 1 row to predict on.
400 BAD REQUEST {"message": "The \"Time\" feature contains the value 'OCT-27', which does not match the original format %m/%d/%y (e.g., '06/24/19'). To upload this data, first correct the format in your prediction dataset and then try the import again. Because some software automatically converts the format for display, it is best to check the actual format using a text editor."} Prediction row has a different format than the rest of the data.
400 BAD REQUEST {"message": "The following errors are found:\n • The prediction data must contain historical values spanning more than 35 day(s) into the past. In addition, the target cannot have missing values or missing rows which are used for differencing"} Provided dataset has fewer than the required 35 rows of historical data.
400 BAD REQUEST {"message": {"forecastPoint": "Invalid RFC 3339 datetime string: "}} Provided an empty or non-valid forecastPoint.
404 NOT FOUND {"message": "Deployment :deploymentId cannot be found for user :userId"} Deployment was removed or doesn’t exist.
422 UNPROCESSABLE ENTITY {"message": "Predictions on models that are not time series models are not supported on this endpoint. Please use the predict endpoint instead."} Provided deploymentId that is not for a time series project.
422 UNPROCESSABLE ENTITY {"message": {"relaxKnownInAdvanceFeaturesCheck": "value can't be converted to Bool"}} Provided an empty or non-valid value for relaxKnownInAdvanceFeaturesCheck'.

Updated February 16, 2024