Compute Metrics for a Metric Block

post/extensions/roboledger/{graph_id}/operations/compute-metrics

Resolves the Derive rules scoped to a metric block (block_type='metric'), binds each rule's operands to the entity's most recent persisted report facts at period_end, evaluates, and upserts the period's standing factset_type='metric' FactSet — one per (structure, entity, period_end), so successive runs accumulate the time series and re-running a period replaces its values. Metrics with missing operands or undefined ratios are skipped with a reason, never errored.

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
`structure_id`required	string	Metric block structure (block_type='metric') to compute.
`period_end`required	string (date)	Period end to compute at. Operands bind to report facts whose period_end matches exactly (instant balances as of this date; durations ending on it).
`period_start`optional	string (date)	Optional lower bound for duration-operand binding and the standing FactSet's period_start.
`entity_id`optional	string	Entity to compute for. Defaults to the graph's earliest-created entity (the primary entity for single-entity graphs).
`scenario_id`optional	string	Compute on a scenario slice: operands bind that scenario's facts (actuals as the fallback across the seam) and the standing metric set is stamped with the scenario. None (the default) computes actuals only. Pass a forecast block's structure id after compute-forecast to extend the metric series into its forward months.

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/compute-metrics" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "period_end": "2026-03-31",
  "structure_id": "str_key_financial_metrics"
}'

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

ComputeMetricsResponse

Command-specific result payload

ComputeMetricsResponse fields

Field Type Description

structure_idrequired string

entity_idrequired string

period_endrequired string (date)

fact_set_idoptional

string

Standing metric FactSet for the period — None when every metric was skipped and no prior set existed.

computedoptional

ComputedMetricLite[]

One metric computed by a ``compute-metrics`` run.

ComputedMetricLite fields

Field	Type	Description
`rule_id`required	string	Derive rule that produced the value.
`element_id`required	string	Metric element the fact was written for.
`element_qname`optional	string	Metric element qname (e.g. rs-metric:CurrentRatio).
`name`required	string	Metric display name.
`value`required	number	Computed value.
`unit`required	string	Fact unit — 'USD' for monetary, 'days' for days, else 'pure'.
`period_type`required	string	'instant' or 'duration'.
`item_type`optional	string	Format family from the metric element (monetary \| ratio \| percent \| multiple \| days). None means untyped; fall back to unit.

skippedoptional

SkippedMetricLite[]

One metric a ``compute-metrics`` run could not compute. Soft-fail by design: a missing operand fact (e.g. InterestExpense for a debt-free entity) or an undefined ratio (division by zero) skips the metric with a reason — it never errors the run.

SkippedMetricLite fields

Field	Type	Description
`rule_id`required	string	Derive rule that was skipped.
`element_qname`optional	string	Metric element qname the rule targets.
`reason`required	string	Why the metric was skipped.
`missing`optional	string[]	Operand qnames with no bound fact at the period, when applicable.

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

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

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