Training

With datasets successfully uploaded, it's time to train forecasting models for the datasets by calling the Start Trainer endpoint. Note that this is not the process that creates predictions from the current date, but a prerequisite to creating predictions. Each dataset needs to have a model trained and stored in order to create predictions when the prediction process is run (with the Create Prediction endpoint, see Prediction).

The parameters that are set when the Start Trainer endpoint is called are the same ones that will be used in the prediction process. If these parameters change, the training process needs to be rerun. However, these parameters are not expected to change often, as the granularity and horizon that a planner wants for the forecasts should be constant. The example payload and snippet from the API reference below show the parameters that clients set for each dataset in a Start Trainer job.

Example Start Trainer payload

An example of a Start Trainer payload. Note that the startDate and endDate fields are optional and do not need to be given.

{
  "datasetId": "f1c78da657c3",
  "frequency": "M",
  "horizon": 4
}

Frequency means granularity

In the API schema for the Start Trainer endpoint, you will see the term frequency being used for the concept granularity that was introduced in Forecasts. The parameter frequency will be renamed to granularity.

Start Trainer Parameters

Array

datasetId required	string The unique dataset ID (unique product) to run the training process for.
frequency required	string Enum: "D" "W" "M" The frequency (granularity) the model is trained to predict for, which determines the granularity of the returned forecast. Acceptable values are: D - Day W - Week M - Month
horizon required	integer >= 1 The forecast horizon, i.e. the number of time steps (days, weeks, months or years) ahead that are forecasted. The horizon needs to longer than the period, we want to cover demand for, but less than 1.5 year. For the best performance, the horizon should be as short as possible.

[

• {

  • "datasetId": "string",
  • "frequency": "D",
  • "horizon": 1

  }

]

Forecasting from the Beginning of a Time Step

Forecasts are always provided for the next horizon time steps, where one time step is either a day, week, or month, depending on the frequency parameter set when the /start_trainer endpoint was called.

A forecast can be requested when the current date is in the middle of a time step. This can be handled in different ways. Our approach is to always forecast from and including the current day, week, or month. For example, if a forecast is requested on October 14th, the frequency parameter is set to "M", and horizon is set to 3, the forecast will be for October (the entire month), November and December. Note that the forecast will be at least equal to the sales recorded before October 14th.

Enough Horizon for the Planning Period

When placing an order for a product, inventory planners want to cover demand for the product in an upcoming planning period (more details in Purchase Order Suggestions). Hence, the forecast horizon must be set such that the forecast is long enough to cover this planning period. To cover all edge cases, it is needed to add one unit of the frequency parameter. For example, if the planning period is 2 months, and frequency is "M", the horizon should be at least 3.

Keeping Models Up to Date

Models do not need to be trained daily. The Start Trainer endpoint should not need to be called more than bi-weekly, and in most cases, monthly or quarterly is enough. This functionality should be linked to the granularity set. Follow the table below when setting up the scheduled jobs.

Current Frequency	Recommended Training Frequency
Daily	Bi-weekly
Weekly	Monthly
Monthly	Quarterly

Step-by-step instructions

1. Determine the tenant and dataset(s) to run the trainer job for.
2. Create the parametersArray with parameters for each dataset.
3. Send a POST request to /start_trainer, following the schema in the API reference.
   • The endpoint will return a jobId.
4. Do one of the following...
   • Call GET /status with the tenantId and jobId in the header until the status is “success”.
   • Provide a webhook in the body of the POST request in step 3 to receive a request when the job is finished running. See the Callbacks below for details about this request.

Error Messages

Error Code	Error message	Action	Example
SUCCESS	Training succeeded.	Job succeeded.
NO_DATA	No data has been uploaded for the dataset.	Check that data has been uploaded for the dataset.
INVALID_START_DATE	Start date format is invalid (should be YYYY-MM-DD), or start date is after current date.	Check that startDate is on a valid date format (YYYY-MM-DD) and not after current day.	startDate = "20241-10-07" or startDate = "2073-08-31"
HORIZON_TOO_LONG	Horizon is longer than 1.5 years.	Decrease horizon to be at most 1.5 years (18 months, 78 weeks or 547 days)	horizon = 18, freq = M or horizon = 90, freq = W
INVALID_HISTORICAL_DATA	Historical data is insufficient or in the future.	Check that at least one full period of data has been uploaded that is before the current day. Possibly change the freezeDate if this is given.	freezeDate = "1996-04-17"