Skip to main content

Forecast API integration

A trained forecast is one POST. Send how many steps ahead you want. Put the prediction map in an application, a website, a data pipeline, or an internal portal. The model already holds the history from training. You do not send the past series again.

POST https://predict.heimdallapp.org/forecast/

Headers​

HeaderValue
X-api-keyKey from the forecast page. Shown once.
X-usernameYour Heimdall username.
x-forecast-idThe id in /forecast/{id}.

A missing or wrong username, forecast id, or key returns 404 with detail set to Invalid Username, Invalid Forecast ID, or Invalid API Key.

Body​

time_windows is the number of steps. The step size is the interval you chose when you trained the forecast: hourly, daily, weekly, monthly, or quarterly. You do not send that interval again, and you do not send the historical series.

exog is optional. Include it only when the forecast was trained with extra columns besides the time column and the value column. Each key is one of those column names. Each value is a list with time_windows numbers, in order, for the future steps. An unknown column returns 400.

{
  "time_windows": 3,
  "exog": {}
}

With one extra column named price:

{
  "time_windows": 3,
  "exog": {
    "price": [10.0, 11.0, 12.0]
  }
}

Response​

prediction is a map from the forecast index to the predicted value. The number of entries is time_windows.

{
  "prediction": {
    "2026-01-01": 120.5,
    "2026-02-01": 118.0,
    "2026-03-01": 121.2
  }
}

The keys follow the index of the trained series. This response has no confidence interval.

import requests

response = requests.post(
    "https://predict.heimdallapp.org/forecast/",
    headers={
        "X-api-key": "YOUR-API-KEY",
        "X-username": "YOUR-USERNAME",
        "x-forecast-id": "YOUR-FORECAST-ID",
    },
    json={"time_windows": 3, "exog": {}},
)
print(response.json()["prediction"])

The key is on the forecast page, shown once. x-forecast-id is the id in /forecast/{id} and in the sample on the API Integration tab.

Next​