Endpoints.

This endpoint generates forecasts for your time series data and selects the model automatically.

Request Body

{
  "identifier": "SKU-12345",
  "data": [
    {"date": "2024-01-01", "value": 120},
    {"date": "2024-02-01", "value": 135},
    {"date": "2024-03-01", "value": 155}
  ],
  "periods": 6,
  "frequency": "M",
  "data_type": "sales",
  "confidence_level": 0.80
}

Parameters

quantiles, value_bounds, adjustments, and accumulate also work on POST /v2/batch/forecast. You set each one once for the whole request, or per series. See Batch Processing for how they scope and where the results land. current_period and covariates are the exceptions. They work on POST /v2/forecast only, and batch and grouped requests reject them instead of ignoring them silently.

Data Types

Choosing the winning model (selection_metric)

For every request, the API back-tests a set of candidate models on your own history. It keeps the winning model, which is the one with the smallest error. selection_metric controls which error metric decides the winning model. A lower value is always better.

Response

{
  "result": {
    "identifier": "SKU-12345",
    "tenant_context": null,
    "forecasts": [
      { "period": 1, "date": "2024-04-01", "forecast": 168.5, "lower": 162.3, "upper": 174.7 },
      { "period": 2, "date": "2024-05-01", "forecast": 175.2, "lower": 168.1, "upper": 182.3 }
    ],
    "model_info": {
      "best_model": "AutoETS",
      "models_evaluated": ["AutoETS", "AutoARIMA", "AutoTheta", "SeasonalNaive"],
      "selection_metric": "smape",
      "interval_source": "conformal",
      "validation_performed": true,
      "smape": { "AutoETS": 6.1, "AutoARIMA": 7.4 },
      "mase": { "AutoETS": 0.82, "AutoARIMA": 0.95 }
    }
  },
  "meta": {
    "selection_metric": "smape",
    "timing": {
      "validation": 8.2,
      "selection": 45.6,
      "forecasting": 72.1,
      "total": 125.9
    }
  }
}

Response Fields

quantiles asks for specific points of the predictive distribution per period, instead of just the two band edges. Use it to draw a fan chart, or to pick a service level directly (order to the 0.9 quantile rather than to the mean).

{
  "identifier": "SKU-12345",
  "data": [{"date": "2024-01-01", "value": 120}, {"date": "2024-02-01", "value": 135}],
  "frequency": "M",
  "periods": 3,
  "quantiles": [0.1, 0.5, 0.9]
}

Each forecast row gains a quantiles object. The API does not change the existing lower and upper fields:

{
  "period": 1,
  "date": "2024-03-01",
  "forecast": 168.5,
  "lower": 162.3,
  "upper": 174.7,
  "quantiles": { "0.1": 151.2, "0.5": 168.5, "0.9": 186.0 }
}

adjustments applies your own assumptions on top of the forecast. Examples are "assume we lose the enterprise deal" or "assume the promo lifts Q4 by 20%". This is the deliberate half of scenario planning. The probabilistic half is the band and the quantile fan.

{
  "adjustments": [
    {"type": "multiplier",  "value": 0.8,  "from_period": 3},
    {"type": "level_shift", "value": -500, "from_period": 6, "to_period": 9}
  ]
}

accumulate collapses the forecast path into a single total: Σ (value × survival × discount). The same operation covers cumulative demand over a lead time (safety stock), customer lifetime value, total cost of ownership, and net present value.

{
  "accumulate": {
    "decay": 0.95,
    "discount_rate": 0.10,
    "correlation": 0.5
  }
}

Period 1 is undiscounted and at full survival. by_period carries a running cumulative plus cumulative_lower/cumulative_upper, which is the number a safety-stock calculation actually reads.

Your data can end mid-period, for example daily sales sent on the 20th and forecast monthly. In that case, the API excludes the incomplete period from the model's history, because it would otherwise look like a sudden collapse. The forecast horizon then starts at that period with a full-period forecast. The API reports the exclusion in result.model_info.partial_period_dropped.

A full-period forecast is not the number you pace against a target. Part of the period has already happened. current_period: true adds the projection that accounts for this. The formula is projected_total = actual_to_date + full_period_forecast × (1 − elapsed_fraction):

{
  "result": { "forecasts": [ { "period": 1, "date": "2024-04-30", "forecast": 300.0, "...": "..." } ] },
  "current_period": {
    "applied": true,
    "period_start": "2024-04-01",
    "period_end": "2024-04-30",
    "last_actual_date": "2024-04-20",
    "elapsed_fraction": 0.6667,
    "actual_to_date": 200.0,
    "full_period_forecast": 300.0,
    "forecast_remainder": 100.0,
    "projected_total": 300.0,
    "lower": 283.3,
    "upper": 316.7,
    "assumptions": { "intraperiod_distribution": "uniform" },
    "stored": false
  }
}

A covariate is a series that influences your data without being forecast itself. Promotions, public holidays, price changes, and upstream traffic are all covariates. You send them beside data, in the same shape, and the forecast is conditioned on them.

Covariates need "model": "multivariate". Every other model rejects the request. This is deliberate: the alternative is a forecast that looks conditioned on your promotion calendar while ignoring it, which is worse than a clear error.

{
  "identifier": "SKU-12345",
  "frequency": "M",
  "periods": 6,
  "model": "multivariate",
  "data": [
    {"date": "2024-01-01", "value": 100},
    {"date": "2024-02-01", "value": 180}
  ],
  "covariates": [
    {
      "name": "promo",
      "known_future": true,
      "data": [
        {"date": "2024-01-01", "value": 0},
        {"date": "2024-02-01", "value": 1},
        {"date": "2024-03-01", "value": 0}
      ]
    },
    {
      "name": "web_sessions",
      "data": [
        {"date": "2024-01-01", "value": 1200},
        {"date": "2024-02-01", "value": 1450}
      ]
    }
  ]
}

known_future

known_future says whether you know the covariate's future values. It decides how far the covariate has to reach:

A covariate that falls short of its range is rejected. A known_future covariate that stops at the end of your history is not known-future, and padding it would condition the forecast on values nobody supplied.

The response reports which covariates were used in result.model_info.covariates, so you can confirm the forecast was conditioned rather than take it on trust. Up to 20 covariates per request. covariates works on POST /v2/forecast only. Batch and grouped requests reject it.

Choose the right forecasting model based on your accuracy requirements and budget. All models use the same automatic algorithm selection, but differ in their underlying implementation and computational complexity.

Available Models

Standard Model (Default)

This is the default forecasting model, and it balances accuracy and speed. It suits most use cases and gives reliable forecasts across a wide range of data patterns.

Best for:

• General-purpose forecasting
• High-volume batch processing
• Real-time forecasting needs
• Cost-sensitive applications

{
  "data": [...],
  "periods": 6,
  "frequency": "M"
  // model defaults to "standard" if not specified
}

Advanced Models (+25% cost)

These forecasting models aim for higher accuracy. They work well for new identifiers, smaller datasets, and complex patterns. Two variants exist:

• advanced-quantized is the most thorough advanced variant. It evaluates and ensembles multiple candidate models per request for the highest single-model accuracy, at the cost of slower processing.
• advanced-patched is a patch-based advanced variant. Its response times are comparable to the standard model. Choose it when you want advanced-level accuracy for real-time forecasting.

The API keeps the advanced value for backward compatibility. It behaves the same as advanced-quantized.

Best for:

• New products or identifiers with limited history
• Small to medium datasets (5-50 datapoints)
• Critical forecasts where accuracy matters most
• Complex or irregular patterns

{
  "data": [...],
  "periods": 6,
  "frequency": "M",
  "model": "advanced-quantized"
}

// or for faster responses:
{
  "data": [...],
  "periods": 6,
  "frequency": "M",
  "model": "advanced-patched"
}

Multivariate Model (Covariates, +25% cost)

multivariate is the only model that reads covariates. Pick it when something outside the series drives it and you can measure that thing: a promotion calendar, a holiday flag, a price change, or upstream web sessions.

Without covariates it is an ordinary foundation model, and the other variants are the better tested choice. The reason to reach for it is the extra input, not extra accuracy on its own.

{
  "data": [...],
  "periods": 6,
  "frequency": "M",
  "model": "multivariate",
  "covariates": [
    {
      "name": "promo",
      "known_future": true,
      "data": [
        {"date": "2024-01-01", "value": 0},
        {"date": "2024-02-01", "value": 1}
      ]
    }
  ]
}

Ensemble Model (Best Accuracy, +25% cost)

This is the most accurate model. It combines the standard model and both advanced variants into a single forecast. It smooths extreme outliers for more reliable forecasts.

Best for:

• Mission-critical forecasts requiring highest accuracy
• Data with extreme outliers or volatility
• Strategic planning and long-term projections
• Batch processing where speed is less critical

{
  "data": [...],
  "periods": 6,
  "frequency": "M",
  "model": "ensemble"
}

Auto Model (Learns Per Series, +25% cost)

auto routes each identifier to whichever model has proven most accurate on that series. A new identifier starts on the ensemble. As you send fresh actuals, the API scores every past forecast against what actually happened. It does this for the ensemble and for each member model individually. Once one model beats every alternative by a clear margin across enough matured forecasts, auto switches that identifier to it. While the evidence is thin, or the models are too close to call, the identifier stays on the ensemble.

The response always says which model answered and why, in model_info.auto_selection. It gives the selected model, the reason (no_history, insufficient_evidence, no_clear_winner, or scored_winner), and the per-model accuracy scores behind the decision.

Best for:

• Long-lived identifiers you forecast repeatedly (SKUs, tenants, metrics)
• Catalogs where the best model differs per series
• Integrations that should not hand-tune model choice per series

{
  "data": [...],
  "periods": 6,
  "frequency": "M",
  "identifier": "SKU-12345",
  "model": "auto"
}

API Usage Calculation

The advanced variants (advanced, advanced-quantized, advanced-patched), the multivariate model, the ensemble model and auto consume 25% more API usage than the standard model. This is how it works:

Example Calculation

Quick Model Selection Guide

HTTP Status Codes

Error Response Format

{
  "error": {
    "code": "invalid_data_format",
    "message": "Data array must contain at least 3 datapoints",
    "details": {
      "received_points": 2,
      "minimum_required": 3
    }
  }
}