---
title: "Consolidation Worksheet"
method: POST
path: "/extensions/roboledger/{graph_id}/operations/consolidation-worksheet"
tags: ["RoboLedger: Analytical Views"]
---

# Consolidation Worksheet

`POST /extensions/roboledger/{graph_id}/operations/consolidation-worksheet`

## 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/consolidation-worksheet`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

The group's statement for one window with the entity as the column, read live from the tenant's OLTP ledger: the parent and each member consolidated in full, their combined sum, the consolidation entity's adjustments, the consolidated total, and each equity-method or cost member beside the sum, never in it. Every column renders under the group parent's Reporting Style. Rejected on shared-repository graphs.

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

- ConsolidationWorksheetRequest: Request for consolidation-worksheet (OLTP, entity graphs only).
  - `statement_type` string, required: income_statement | balance_sheet | cash_flow_statement | equity_statement.
  - `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)
  - `limit` integer: Max rows returned. Defaults to the ceiling: the whole statement.

## Response `200`

Successful Response

- OperationEnvelopeConsolidationWorksheetResponse
  - `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` ConsolidationWorksheetResponse: The group's statement with the entity as the column.
    - `graph_id` string, required: The graph read.
    - `entity_id` string, required: The group parent.
    - `statement_type` string, required: The statement rendered.
    - `period` PeriodSpec, required: A single reporting period column. Reports render facts in N period columns side-by-side. Each `PeriodSpec` is one column — its `start`/`end` define the window the report's facts roll up into; `label` is what the renderer prints in the column header. For year-over-year statements, supply two PeriodSpecs (current + comparative); for YTD by quarter, supply four.
      - `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[]: Windows the worksheet does not total, as live-financial-statement leaves them out: before a summed entity's books begin, or, on a cash flow or equity statement, one a member joined or left the group within. When it names `period`, `rows` is empty.
      - `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').
    - `columns` WorksheetColumn[], required: The parent, each member consolidated in full, `combined`, the consolidation entity's adjustments (when the group has one), `consolidated`, then the equity-method and cost members outside the sum. A member outside its membership interval for the period has no column.
      - `key` string, required: The entity id for an entity's column; `combined` and `consolidated` for the two totals.
      - `label` string, required: The entity's name, or the total's.
      - `kind` 'member' | 'combined' | 'adjustments' | 'consolidated' | 'not_summed', required: `member`: the parent or a member consolidated in full. `combined`: the members' sum, nothing eliminated. `adjustments`: the consolidation entity's entries. `consolidated`: combined plus the adjustments. `not_summed`: an equity-method or cost member, shown beside the sum and never in it.
      - `entity_id` string, nullable: The entity the column reads; null on a total.
      - `consolidation_method` string, nullable: The entity's `consolidation_method`; null on a total.
      - `ownership_pct` number, nullable: The parent's share of the entity, where it has one.
      - `in_sum` boolean, required: Whether the column is part of the consolidated total.
    - `rows` WorksheetRow[], required: The union of every column's lines in the parent's Style order; a line zero in every column is left out.
      - `qname` string, required: The rs-gaap concept of the line.
      - `name` string, required: The line's label.
      - `trait` string, nullable: The concept's classification.
      - `values` number[], required: One value per column, aligned with `columns`.
      - `depth` integer: Indentation in the statement.
      - `is_subtotal` boolean: Whether the line is a total.
      - `period_role` string, nullable: On the equity roll-forward, `start` for the beginning-balance row and `end` for the ending-balance row. Null elsewhere.
    - `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_entity_ids` string[]: Entities with no CoA mapping yet, so with no column.
    - `unmapped_count` integer: Unmapped accounts across the summed columns.
    - `truncated` boolean: Whether `limit` cut rows.
  - `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/e661e2d5ca6a?raw)