Skip to main content
GET
/
demand-forecast
Get demand forecast
curl --request GET \
  --url https://api.simcel.io/insights/v1/demand-forecast \
  --header 'Authorization: Bearer <token>'
{
  "meta": {
    "planId": "plan_9xKz2",
    "interval": "M",
    "currency": "USD",
    "generatedAt": "2025-04-14T10:32:00Z"
  },
  "scenarios": [
    {
      "scenarioId": "scen_abc",
      "scenarioName": "Optimistic 2025",
      "scenarioColor": "#6366F1",
      "series": [
        {
          "period": "2025-01",
          "demandVolume": 12400,
          "demandValue": 248000,
          "fillRate": 0.94,
          "forecastAccuracy": 0.88
        },
        {
          "period": "2025-02",
          "demandVolume": 13100,
          "demandValue": 262000,
          "fillRate": 0.96,
          "forecastAccuracy": 0.91
        }
      ]
    },
    {
      "scenarioId": "scen_def",
      "scenarioName": "Conservative 2025",
      "scenarioColor": "#06B6D4",
      "series": [
        {
          "period": "2025-01",
          "demandVolume": 10800,
          "demandValue": 216000,
          "fillRate": 0.91,
          "forecastAccuracy": 0.85
        }
      ]
    }
  ]
}

​
When to use this

Use /demand-forecast when you want to:
  • Track demand evolution over time across planning scenarios
  • Detect demand risk (low fill rates, poor forecast accuracy)
  • Compare an optimistic vs conservative demand plan
  • Feed an AI agent with time-series demand data for anomaly detection

​
Key metrics

FieldDescription
demandVolumeTotal ordered units in the period
demandValueTotal demand at gross sales value (plan currency)
fillRateShare of demand that was fulfilled (0–1)
forecastAccuracy1 − MAPE. How close the forecast was to actuals (only meaningful on actual scenario)

​
groupBy options

ValueDescription
productAggregate across all regions per product family
skuGranular SKU-level breakdown
regionGeographic region grouping
channelSales channel (modern trade, e-comm, traditional, etc.)

​
Example: Monthly demand trend for two scenarios

import requests

client = SimcelClient(api_key="sk_live_...")

resp = client.get("/demand-forecast", params={
    "planId": "plan_9xKz2",
    "scenarioIds": "scen_committed,scen_optimistic",
    "interval": "M",
    "dateFrom": "2025-01-01",
    "dateTo": "2025-12-31",
    "groupBy": "product",
})

for scenario in resp.json()["scenarios"]:
    total_demand = sum(row["demandValue"] for row in scenario["series"])
    print(f"{scenario['scenarioName']}: ${total_demand:,.0f} total demand")
forecastAccuracy is only meaningful when querying the actual scenario or comparing forecast scenarios against actuals. In pure what-if scenarios it reflects the internal model accuracy.

Authorizations

​
Authorization
string
header
required

Obtain a token via POST /auth/token using your API key and secret. Tokens expire after 1 hour.

Query Parameters

​
planId
string
required

The plan identifier to query data against

​
scenarioIds
string[]
required

Comma-separated list of scenario IDs (max 3)

Maximum array length: 3
​
interval
enum<string>
default:M

Time aggregation bucket

Available options:
D,
W,
M,
FY
​
dateFrom
string<date>

Start of the date range (ISO 8601)

​
dateTo
string<date>

End of the date range (ISO 8601)

​
currency
string
default:USD

ISO 4217 currency code for monetary values

​
groupBy
enum<string>
default:product

Dimension to group results by

Available options:
product,
region,
channel,
sku

Response

Demand forecast data per scenario

​
meta
object
​
scenarios
object[]