---
title: "train a versioned per-series daily-state forecast model"
method: POST
path: "/api/forecast-sandbox/consumption/state-model/train"
tags: ["Forecast Sandbox"]
---

# train a versioned per-series daily-state forecast model

`POST /api/forecast-sandbox/consumption/state-model/train`

## Request

- Base URL: `https://api.cernion.de`
- URL: `https://api.cernion.de/api/forecast-sandbox/consumption/state-model/train`
- Auth: none declared

Sandbox only. History/calendar training uses relationship_state_correction_v2; extended features use relationship_state_context_guard_v4 with a protected automatic reference. Both combine: automatic calendar/recency reference plus historically validated state correction. Existing v1/v2/v3 artifacts remain readable. Historical labels and transition models use D-2 availability. Immutable tenant-scoped artifacts. Train requires at least 14 complete days; activating state features requires historical validation. Predict reloads frozen parameters and can persist recent complete-day context without retraining. Live dates beyond 2025 supported; no future knowledge origins.

## Query parameters

- `token` string

## Request body

- object
  - `dataset` object, required
    - `series_id` string, required
    - `unit` 'kWh' | 'kW', required
    - `timezone` string, required
    - `weather_region` string
    - `period_from` string, date, required
    - `period_until` string, date, required
    - `values` object[], required
      - `timestamp` string, date-time, required
      - `value` number, required
      - `available_at` string, date-time
  - `forecast_for` string, date, required
  - `configuration` object: Optional issue_time, extended_features, feature_set, weather_dataset_id/context_dataset_id or inline weather/context. Prediction threshold is saved with the artifact and applied during inference.
    - `prediction_threshold_w` number: Prediction-only deadband in watts. Strictly smaller absolute predictions become zero; actuals and training remain unchanged. 50 W = 0.05 kW = 0.0125 kWh per PT15M. 0 disables filtering. Persisted with state-model artifacts.
  - `token` string: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.

## Response `200`

Version metadata, validation or PT15M forecasts; inspect warnings and state_features_enabled.

- object
  - `series_id` string
  - `artifact_version` string
  - `model_version` string
  - `forecast_values` object[]
  - `validation` object
  - `warnings` string[]

## Other responses

- `400`: Invalid dataset, missing model or incompatible historical origin.
- `500`: Internal forecast/storage error.

---

[API](https://skmtc.dev/cernion/apis/cernion-energy-tools-api.md) · [All operations](https://skmtc.dev/cernion/apis/cernion-energy-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cernion/apis/cernion-energy-tools-api/revisions/cdb94473b538?raw)