---
title: "Live Financial Statement"
method: POST
path: "/extensions/roboledger/{graph_id}/operations/live-financial-statement"
tags: ["RoboLedger: Analytical Views"]
---

# Live Financial Statement

`POST /extensions/roboledger/{graph_id}/operations/live-financial-statement`

## Request

- Base URL: `https://api.robosystems.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/live-financial-statement`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Generate an ad-hoc financial statement directly from the tenant's OLTP ledger data using the active CoA→GAAP mapping. This is the authoritative source for RoboLedger entity graphs — no graph materialization required. One entity's books: `entity_id` names a subsidiary, omitted means the group parent. On the parent, `scope: combined` sums every member consolidated in full at the rs-gaap concepts for the months each was a member, nothing eliminated, and `scope: consolidated` adds the consolidation entity's entries — the eliminations and noncontrolling interest. Rejected on shared-repository graphs; those should use `financial-statement-analysis` instead.

**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.

## Path parameters

- `graph_id` string, required

## Headers

- `Idempotency-Key` string, nullable

## Request body

- LiveFinancialStatementRequest: Request for live-financial-statement (OLTP, entity graphs only).
  - `entity_id` string, nullable: The entity whose books this acts on, by id. Omit for the group parent — the single-entity default.
  - `statement_type` string, required: income_statement | balance_sheet | cash_flow_statement | equity_statement. `equity_statement` is provisional — equity balances, not a rollforward — and is not offered on the MCP surface until it articulates.
  - `period_start` string, date, nullable: Explicit window start. Overrides period_type/fiscal_year.
  - `period_end` string, date, nullable: Explicit window end. Overrides period_type/fiscal_year.
  - `period_type` string, nullable: annual | quarterly | instant (ignored when dates supplied)
  - `fiscal_year` integer, nullable: Fiscal year for annual window (anchored on FiscalCalendar)
  - `scope` 'entity' | 'combined' | 'consolidated', nullable: `entity` (the default): one entity's own books. `combined`: on the group parent, every member consolidated in full rendered under the parent's Reporting Style and summed per rs-gaap concept, each for the months it was a member — the pre-adjustment total, nothing eliminated. `consolidated`: the same sum plus the consolidation entity, whose eliminations and noncontrolling interest are the adjustments column, so a group that posts its consolidating entries there reads its consolidated statement. An equity-method or cost member is never summed (its `consolidation_method` says so). Both group scopes are read on the group parent only (422 on a subsidiary). An entity with no CoA mapping yet contributes nothing and is left out of `combined_entity_ids`.
  - `consolidated` boolean: The older spelling of `scope: consolidated`, kept for callers that pass it; `scope` wins when both are given.
  - `limit` integer: Max fact rows returned. Defaults to the ceiling so a statement is never cut mid-section — visible rows would stop footing to visible subtotals. Lower it only for a preview.

## Response `200`

Successful Response

- OperationEnvelopeLiveFinancialStatementResponse
  - `operation` string, required: Kebab-case operation name
  - `operationId` string, required: op_-prefixed ULID for audit and SSE correlation
  - `status` 'completed' | 'pending' | 'failed', required: Operation lifecycle state
  - `result` LiveFinancialStatementResponse: Rendered OLTP-backed ad-hoc statement.
    - `graph_id` string, required
    - `entity_id` string, nullable: The entity whose books were rendered.
    - `scope` string: What was rendered: `entity`, `combined` (the members summed, nothing eliminated) or `consolidated` (the members plus the consolidation entity's adjustments).
    - `consolidated` boolean: Whether the group's entities were summed into this — true for the `combined` and `consolidated` scopes.
    - `combined_entity_ids` string[]: The entities summed, parent first; on `consolidated` the consolidation entity comes last.
    - `statement_type` string, required
    - `periods` PeriodSpec[], required: Rendered columns, aligned with each row's `values`. Current and prior for income_statement and balance_sheet; current only for cash_flow_statement — the prior period is pivoted as the indirect-method delta basis and not rendered.
      - `start` string, date, required: Period start date (inclusive). Window the column rolls up.
      - `end` string, date, required: Period end date (inclusive). Window the column rolls up.
      - `label` string, required: Column header label (e.g. 'FY2025 Q3', '2024', 'YTD').
    - `omitted_periods` PeriodSpec[]: Columns left out because they reach back before the books begin: on books that start from an opening balance, a flow statement column that starts before the first day it covers, or a balance sheet dated before it. They would show a partial figure, not the months before the books. On a group read, also a cash flow or equity statement column a member joined or left the group within.
      - `start` string, date, required: Period start date (inclusive). Window the column rolls up.
      - `end` string, date, required: Period end date (inclusive). Window the column rolls up.
      - `label` string, required: Column header label (e.g. 'FY2025 Q3', '2024', 'YTD').
    - `facts` LiveStatementFactRow[], required
      - `qname` string, required
      - `name` string, required
      - `trait` string, nullable
      - `values` number[], required
      - `depth` integer
      - `is_subtotal` boolean
      - `period_role` string, nullable: On the equity roll-forward, `start` for the beginning-balance row and `end` for the ending-balance row. Null elsewhere.
    - `fact_count` integer, required
    - `validation` ValidationCheckResponse: Aggregate result of running reporting rules over a structure. Every rule runs once per rendered period column; on a multi-column statement each failure and warning is prefixed with the column it was found in (`[Prior] …`).
      - `passed` boolean, required: True iff at least one rule ran and every rule produced zero failures on every rendered column. False when nothing was checked (`status == 'inconclusive'`).
      - `status` string, required: `passed` — every rule ran on every column with zero failures; `failed` — at least one rule failed; `inconclusive` — no validation rules exist for this block type, so nothing was checked.
      - `checks` string[], required: Names of rules that were evaluated.
      - `failures` string[], required: Human-readable descriptions of rule failures.
      - `warnings` string[], required: Non-blocking advisories from rule evaluation.
    - `unmapped_count` integer
    - `truncated` boolean
  - `at` string, required: ISO-8601 UTC timestamp
  - `createdBy` string, nullable: User ID that initiated the operation
  - `idempotentReplay` boolean: True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

## Other responses

- `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

---

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