Build Fact Grid

post/extensions/roboledger/{graph_id}/operations/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.

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

elementsoptional

string[]

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

canonical_conceptsoptional

string[]

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

periodsoptional

string[]

Period end dates (YYYY-MM-DD format)

entityoptional

string

Filter by entity ticker, CIK, or name

entitiesoptional

string[]

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

formoptional

string

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

fiscal_yearoptional

integer

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

fiscal_periodoptional

string

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

period_typeoptional

string

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

include_summaryoptional

boolean

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

Default: false

limitoptional

integer

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.

Default: 250

Constraints: 1–5000

view_configoptional

ViewConfig

Aspect scoping configuration

ViewConfig fields

Field Type Description

rowsoptional

ViewAxisConfig[]

Row axis configuration

ViewAxisConfig fields

Field Type Description

typerequired

string

Axis type: 'element', 'period', 'entity'

include_null_dimensionoptional

boolean

Include facts where this aspect is absent (default: false)

Default: false

selected_membersoptional

string[]

Specific members to include (e.g., ['2024-12-31', '2023-12-31'])

columnsoptional

ViewAxisConfig[]

Column axis configuration

ViewAxisConfig fields

Field Type Description

typerequired

string

Axis type: 'element', 'period', 'entity'

include_null_dimensionoptional

boolean

Include facts where this aspect is absent (default: false)

Default: false

selected_membersoptional

string[]

Specific members to include (e.g., ['2024-12-31', '2023-12-31'])

Example request

curl · example 1 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/build-fact-grid" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "elements": [
    "us-gaap:Assets"
  ],
  "entities": [
    "NVDA"
  ],
  "form": "10-K",
  "period_type": "annual"
}'

curl · example 2 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/build-fact-grid" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "canonical_concepts": [
    "revenue"
  ],
  "entities": [
    "NVDA",
    "AMD"
  ],
  "fiscal_period": "FY",
  "form": "10-K",
  "view_config": {
    "columns": [
      {
        "selected_members": [
          "2022-12-31",
          "2023-12-31",
          "2024-12-31"
        ],
        "type": "period"
      }
    ]
  }
}'

curl · example 3 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/build-fact-grid" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "elements": [
    "us-gaap:Assets",
    "us-gaap:Liabilities",
    "us-gaap:StockholdersEquity"
  ],
  "include_summary": true,
  "period_type": "instant",
  "periods": [
    "2026-03-31"
  ]
}'

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

ViewResponse

Command-specific result payload

ViewResponse fields

Field Type Description

metadatarequired

ViewMetadata

View metadata

ViewMetadata fields

Field	Type	Description
`view_id`required	string	Unique view identifier
`facts_processed`required	integer	Number of facts processed
`construction_time_ms`required	number	Time to build view in milliseconds
`source`required	string	Data source type
`period_start`optional	string	Period start date
`period_end`optional	string	Period end date
`truncated`optional	boolean	True when more facts matched than `limit` allowed. The returned facts are the most recent by period; narrow the filters or raise `limit` to see the rest. Default: `false`

dimensionsoptional

Dimension[]

Aspects spanned by the returned facts

Dimension fields

Field Type Description

namerequired

string

Dimension name (e.g., 'Element', 'Period')

typerequired

DimensionType

Dimension type

One of: element, period, entity

membersoptional

string[]

List of dimension members

factsoptional

FactRecord[]

Deduplicated fact records

FactRecord fields

Field	Type	Description
`element_id`required	string	Element qname (e.g., 'us-gaap:Assets')
`element_name`optional	string	Element local name
`period_start`optional	string	Period start date (YYYY-MM-DD); null for instant facts. A duration fact is identified by (start, end) — two facts for the same element can share an end date and differ only here (e.g. a quarterly and a year-to-date figure from the same 10-Q).
`period_end`optional	string	Period end date (YYYY-MM-DD)
`duration_type`optional	string	Period duration classification (e.g. 'quarterly', 'nine_months', 'annual'); null for instant facts. Use with period_start to tell overlapping windows apart.
`value`optional	number	Numeric fact value
`unit`optional	string	Unit of measure (e.g., 'USD')
`entity_ticker`optional	string	Entity ticker; present only when an entity filter was applied
`entity_name`optional	string	Entity name; present only when an entity filter was applied

summaryoptional

object

Per-element aggregates, only when include_summary=true. total and average span every returned period, so they are present for duration elements only — instants omit both (a balance summed across periods is not a balance). Overlapping duration windows sharing a period_end (quarter + year-to-date) contribute only the narrowest window, so a quarter is never double-counted inside its own YTD figure.

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation

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