Compute Forecast for a Forecast Block

post/extensions/roboledger/{graph_id}/operations/compute-forecast

Walks a forecast block's driver cascade month-by-month forward from its base period: lever-driven rs-driver Derive rules in dependency order, carry-forward for unmodeled income-statement lines, calc-DAG subtotals — upserting one scenario income-statement FactSet (plus a working-capital balance-sheet set) per forward month, all keyed by the block's scenario_id (NULL = actuals; scenario reads pass it as a filter). Re-running replaces each month's values. Rules with missing lever months or unbound operands are skipped with a reason (their targets fall back to carry-forward), never errored. Deterministic and non-AI — no credits consumed.

Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field	Type	Description
`structure_id`required	string	Forecast block structure (block_type='forecast') to compute.
`months`optional	integer	Forward months to compute — defaults to the block's full horizon_months; must not exceed it (lever assertions don't extend past the horizon).
`entity_id`optional	string	Entity to compute for. Defaults to the lever FactSet's entity (the entity the scenario was authored against).

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/compute-forecast" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "structure_id": "struct_fy26_budget"
}'

Responses

200 Successful Response

Field Type Description

operationrequired

string

Kebab-case operation name

operationIdrequired

string

op_-prefixed ULID for audit and SSE correlation

statusrequired

string

Operation lifecycle state

One of: completed, pending, failed

resultoptional

ComputeForecastResponse

Command-specific result payload

ComputeForecastResponse fields

Field Type Description

structure_idrequired string

scenario_idrequired

string

The scenario key every emitted FactSet carries — the forecast block's own structure id.

entity_idrequired string

base_periodrequired

string

Origin month of the block's authored horizon window — where its levers are keyed from. Equal to ``anchor_period`` unless the walk re-anchored at the seam.

anchor_periodrequired

string

Month the walk actually seeded its opening balances from. With ``base_anchor='seam'`` this advances to the newest closed month as periods close, so the first forward month rolls off real balances instead of a stale base; with ``'fixed'`` it always equals ``base_period``.

monthsrequired

integer

Forward months requested.

months_computedoptional

ForecastMonthLite[]

One computed forward month in a ``compute-forecast`` response.

ForecastMonthLite fields

Field	Type	Description
`period`required	string	Month key (``YYYY-MM``).
`period_start`required	string (date)
`period_end`required	string (date)
`income_statement_fact_set_id`optional	string	Scenario IS FactSet upserted for the month.
`balance_sheet_fact_set_id`optional	string	Scenario BS FactSet upserted for the month — the full roll: carry-forward, rule-driven working capital, schedule movements, RE roll, balancing cash (A = L + E by construction).
`cash_flow_fact_set_id`optional	string	Scenario CF FactSet upserted for the month — indirect-method, derived from BS deltas + NI, reconciled to the balancing ΔCash.
`computed_count`optional	integer	Number of facts emitted for the month across all sets. Default: `0`
`verification_passed`optional	boolean	Whether every rule evaluated against the month's scenario sets passed. Three states, and the third is not the first: ``true`` = rules ran and all passed; ``false`` = at least one failed or errored, which halts the walk (see ``halted_at``); ``null`` = no rules ran, so the month is unverified rather than verified. Treat null as absence of evidence, never as a pass.
`verification_failures`optional	string[]	Failed/errored rule messages for the month (capped).

halted_atoptional

string

Month (``YYYY-MM``) where the walk stopped because verification failed, or null if it ran the full horizon. Each month's opening balances are the previous month's closing balances, so computing past a failure yields months derived from a known-wrong one rather than merely unverified months. When set, ``months_computed`` ends at this month and is shorter than ``months``; the failing month's facts are kept so the failure can be inspected.

skippedoptional

SkippedForecastLite[]

One rule/month soft-skip in a ``compute-forecast`` response. A skipped rule never aborts the walk — its target falls back to the carry-forward value for that month (when a prior value exists).

SkippedForecastLite fields

Field	Type	Description
`rule_id`optional	string
`element_qname`optional	string
`period`required	string	Month key (``YYYY-MM``) of the skip.
`reason`required	string
`missing`optional	string[]

diagnosticsoptional

string[]

Articulation notes — a missing cash/earnings anchor, schedule contributions with no base-set landing spot, an absent cash-flow structure. Informational; the walk still computed.

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation (null for legacy callers)

idempotentReplayoptional

boolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Default: false

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
409	Idempotency-Key conflict — key reused with different body
422	Validation error
429	Rate limit exceeded
500	Internal server error