RoboLedger: Analytical Views

Build Fact Grid

Queries LadybugDB Fact nodes by element qnames, with filters for periods and entities. Returns deduplicated facts plus the aspects they span — arranging them into a table is the consumer's job, since collapsing cells safely requires the full aspect signature. Works on both roboledger tenant graphs (post-materialization) and the SEC shared repository. Canonical concepts and the form and fiscal-period filters exist on shared repositories only: a ledger's graph carries none of them, and a query by them there is refused rather than answered with nothing.

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.

post/extensions/roboledger/{graph_id}/operations/build-fact-grid

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/build-fact-grid
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

graph_idstring required

Headers

Idempotency-Keystring nullable

Request body

elementsstring[]

Element qnames (e.g., 'us-gaap:Assets'). Can combine with canonical_concepts.

canonical_conceptsstring[]

Canonical concept names (e.g., 'revenue', 'net_income'). Matches all mapped qnames. Shared repositories only.

periodsstring[]

Period end dates (YYYY-MM-DD format)

entitystring nullable

Filter by entity ticker, CIK, or name

entitiesstring[]

Filter by multiple entity tickers (e.g., ['NVDA', 'AAPL'])

formstring nullable

Filter by SEC filing form type (e.g., '10-K', '10-Q'). Shared repositories only.

fiscal_yearinteger nullable

Filter by fiscal year (e.g., 2024). Shared repositories only.

fiscal_periodstring nullable

Filter by fiscal period (e.g., 'FY', 'Q1', 'Q2', 'Q3'). Shared repositories only.

period_typestring nullable

Filter by period type: 'annual', 'quarterly', or 'instant'

include_summaryboolean

Include summary statistics per element. An element reported in more than one unit has none.

limitinteger

Maximum facts to return. Applied after deduplication and sorting, so truncation keeps the most recent periods. Check metadata.truncated to see whether more facts matched.

Example request

{
  "elements": [
    "us-gaap:Assets"
  ],
  "entities": [
    "NVDA"
  ],
  "form": "10-K",
  "period_type": "annual"
}

Response

Successful Response

operationstring required

Kebab-case operation name

operationIdstring required

op_-prefixed ULID for audit and SSE correlation

status'completed' | 'pending' | 'failed' required

Operation lifecycle state

atstring required

ISO-8601 UTC timestamp

createdBystring nullable

User ID that initiated the operation

idempotentReplayboolean

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

Changes

No recorded changes to this operation across all 1 revision of this API.