Grouped Forecasting with Reconciliation

New

• New POST /v2/forecast/grouped endpoint forecasts a set of related series that roll up to a total, with reconciliation so the parts actually sum to the whole. Declare a hierarchy like ["region", "plan"], send one series per segment, and every level — each region, and the grand total — comes back forecast and coherent: no more presenting five segment forecasts and a total that disagrees with their sum. Submission returns immediately with an id; poll GET /v2/forecast/grouped/{id} for the result while the hierarchy processes in the background, so large hierarchies aren't limited by request timeouts.
• New structured segment field, independent of tenant_context: tenancy keeps meaning "whose data is this", segment means "which slice". Each slice — and each aggregate level — becomes its own entity with independently tracked history and forecast accuracy, so an agency can segment a client's MRR by plan without giving up the tenant key that separates their clients.
• Two reconciliation methods. bottom_up (default) forecasts the leaves and derives every aggregate as the exact sum of its children. min_trace forecasts every level independently — the smoother aggregate series included — and optimally redistributes the disagreement into a coherent set, reporting each node's unreconciled forecast alongside so you can see what coherence cost.
• Aggregate confidence ranges are built from the children's uncertainties under a stated correlation assumption between sibling errors (default 0.5, overridable per request) — not by summing the children's bounds, which assumes every segment misses low at once. The assumption in force is always echoed in the response, and when a range genuinely can't be computed the response says why instead of inventing one.

Improved

• New Grouped Forecasting documentation, and the Patterns & Segmentation guide now points at it wherever it previously advised working around incoherent roll-ups by hand.