---
title: "Household action window(s) (Home+)"
method: POST
path: "/v1/optimize/cheapest-window"
---

# Household action window(s) (Home+)

`POST /v1/optimize/cheapest-window`

## Request

- Base URL: `https://voltcast.com/api`
- URL: `https://voltcast.com/api/v1/optimize/cheapest-window`
- Auth: HTTP bearer

## Request body

- object
  - `zone` string, required
  - `duration_minutes` integer, required
  - `from` string, date-time
  - `to` string, date-time
  - `count` integer
  - `objective` 'cost' | 'carbon' | 'balanced': Cost is the production default. Carbon/balanced are experimental trailing historical production-profile heuristics, not forward carbon forecasts or emissions-reduction claims.
  - `tariff` object: Optional user-supplied variable household charges. Fixed monthly charges are excluded.
    - `grid_fee_eur_kwh` number
    - `supplier_markup_eur_kwh` number
    - `vat_percent` number

## Response `200`

Ranked non-overlapping windows with wholesale price, user-entered bill context and source basis. Experimental carbon/balanced modes add a historical profile estimate with explicit no-forecast/no-emissions-claim metadata.

## Other responses

- `422`: Invalid range/input, insufficient price curve, or stale/incomplete carbon profile for a carbon objective.

---

[API](https://skmtc.dev/voltcast/apis/voltcast-api.md) · [All operations](https://skmtc.dev/voltcast/apis/voltcast-api/llms.txt) · [OpenAPI document](https://skmtc.dev/voltcast/apis/voltcast-api/revisions/9c39e52e3eed?raw)