RoboSystems
Browse the API reference
Overview

Build Fact Grid

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

Part of Extensions: RoboLedger.

Queries LadybugDB Fact nodes by element qnames or canonical concepts, with filters for periods, entities, form, and fiscal context. 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.

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

NameTypeDescription
graph_idrequiredstringGraph Id

Header parameters

NameTypeDescription
Idempotency-KeyoptionalstringIdempotency-Key

Request body

Required, application/json.

FieldTypeDescription
elementsoptionalstring[]

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

canonical_conceptsoptionalstring[]

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

periodsoptionalstring[]

Period end dates (YYYY-MM-DD format)

entityoptionalstring

Filter by entity ticker, CIK, or name

entitiesoptionalstring[]

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

formoptionalstring

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

fiscal_yearoptionalinteger

Filter by fiscal year (e.g., 2024)

fiscal_periodoptionalstring

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

period_typeoptionalstring

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

include_summaryoptionalboolean

Include summary statistics per element

Default: false

limitoptionalinteger

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

view_configoptionalViewConfig

Aspect scoping configuration

ViewConfig fields
FieldTypeDescription
rowsoptionalViewAxisConfig[]

Row axis configuration

ViewAxisConfig fields
FieldTypeDescription
typerequiredstring

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

include_null_dimensionoptionalboolean

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

Default: false

selected_membersoptionalstring[]

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

columnsoptionalViewAxisConfig[]

Column axis configuration

ViewAxisConfig fields
FieldTypeDescription
typerequiredstring

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

include_null_dimensionoptionalboolean

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

Default: false

selected_membersoptionalstring[]

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

Example request

curl
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"
}'

Responses

200 Successful Response

FieldTypeDescription
operationrequiredstring

Kebab-case operation name

operationIdrequiredstring

op_-prefixed ULID for audit and SSE correlation

statusrequiredstring

Operation lifecycle state

One of: completed, pending, failed

resultoptionalViewResponse

Command-specific result payload

ViewResponse fields
FieldTypeDescription
metadatarequiredViewMetadata

View metadata

ViewMetadata fields
FieldTypeDescription
view_idrequiredstring

Unique view identifier

facts_processedrequiredinteger

Number of facts processed

construction_time_msrequirednumber

Time to build view in milliseconds

sourcerequiredstring

Data source type

period_startoptionalstring

Period start date

period_endoptionalstring

Period end date

truncatedoptionalboolean

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

dimensionsoptionalDimension[]

Aspects spanned by the returned facts

Dimension fields
FieldTypeDescription
namerequiredstring

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

typerequiredDimensionType

Dimension type

One of: element, period, entity

membersoptionalstring[]

List of dimension members

factsoptionalFactRecord[]

Deduplicated fact records

FactRecord fields
FieldTypeDescription
element_idrequiredstring

Element qname (e.g., 'us-gaap:Assets')

element_nameoptionalstring

Element local name

period_startoptionalstring

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_endoptionalstring

Period end date (YYYY-MM-DD)

duration_typeoptionalstring

Period duration classification (e.g. 'quarterly', 'nine_months', 'annual'); null for instant facts. Use with period_start to tell overlapping windows apart.

valueoptionalnumber

Numeric fact value

unitoptionalstring

Unit of measure (e.g., 'USD')

entity_tickeroptionalstring

Entity ticker; present only when an entity filter was applied

entity_nameoptionalstring

Entity name; present only when an entity filter was applied

summaryoptionalobject

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.

atrequiredstring

ISO-8601 UTC timestamp

createdByoptionalstring

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

idempotentReplayoptionalboolean

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

Default: false

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