Covariate Support

The API accepts covariates, aligns them to the cleaned series and reports, per column, whether each one reached the model. The model (hora-1.0) does not use covariates today: no column is handed to the model, so every column that passes the data checks below is reported with reason: "model_unsupported". The per-column report in the response is authoritative for whether a column reached the model. The forecast itself is always returned. Whether covariates improve accuracy depends on your data; evaluate with your own backtests.

1. Two kinds of covariates

Past covariates: extra numeric fields on series rows, recorded alongside historical y (for example past temperature or operating state).
Future covariates: columns that are also given in future_covariates, with one row per forecast stamp (for example holidays, schedules or published weather forecasts). A future column needs its history on the series rows as well.

forecast-with-covariates.json

{
"model": "hora-1.0",
"h": 2,
"freq": "1h",
"series": [
  {"unique_id": "meter-001", "ds": "2026-09-01T00:00:00Z", "y": 120.5, "temperature": 27.4, "is_holiday": 0},
  {"unique_id": "meter-001", "ds": "2026-09-01T01:00:00Z", "y": 118.2, "temperature": 26.9, "is_holiday": 0}
],
"future_covariates": [
  {"unique_id": "meter-001", "ds": "2026-09-01T02:00:00Z", "temperature": 26.5},
  {"unique_id": "meter-001", "ds": "2026-09-01T03:00:00Z", "temperature": 26.1}
]
}

2. Rules and rejections

Input	Behavior
`y` in a `future_covariates` row	422 `FUTURE_COVARIATES_INVALID`.
A `future_covariates` column missing from the `series` rows	422 `COVARIATE_COLUMN_MISMATCH`, `details.future_only` lists the columns.
More than 8 covariate columns	422 `VALIDATION_ERROR` with `details.covariates` and `details.max_covariates`.
A column that is not numeric (booleans count as 0/1)	Not used, reported `non_numeric`.
Long gaps, or future values that do not cover every forecast stamp	Not used, reported `data_incomplete`.
Short gaps (up to the policy's short-gap limit)	Filled linearly when `clean_exog` is `true` (default); with `clean_exog: false` any gap makes the column `data_incomplete`.
`options.cleaning.preset: "raw"`	Covariates are not aligned; every column is reported `raw_preset`.

Covariates follow the target exactly: the same timestamp snapping, duplicate handling and segment as y. They are never repaired beyond the short-gap fill above.

3. Reading the report

Each model_input[] entry carries covariates[] when the entity had covariate columns:

model-input-covariates.json

{
"unique_id": "meter-001",
"covariates_used": false,
"covariates": [
  {"name": "temperature", "role": "future", "used": false, "reason": "model_unsupported"},
  {"name": "is_holiday", "role": "past", "used": false, "reason": "model_unsupported"}
]
}

Once a model starts using covariates, columns handed to it will report used: true and covariates_used becomes true. Besides the cleaning reasons above, role_unsupported means the model only takes past covariates and the column was sent as future, and limit_exceeded means the column is beyond the model's own covariate limit.