Financial Statement Analysis
/extensions/roboledger/{graph_id}/operations/financial-statement-analysisPart of Extensions: RoboLedger.
Query a rendered financial statement from the graph-backed XBRL hypercube (Structure → FactSet → Fact). Works on the SEC shared repository today and on any RoboLedger tenant graph whose ledger has been materialized to LadybugDB. For shared-repo graphs, provide ticker to auto-resolve the latest filing; for tenant graphs, provide report_id explicitly.
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-Keyheader. - Bearer token in the
Authorizationheader.
Path parameters
| Name | Type | Description |
|---|---|---|
graph_idrequired | string | Graph Id |
Header parameters
| Name | Type | Description |
|---|---|---|
Idempotency-Keyoptional | string | Idempotency-Key |
Request body
Required, application/json.
| Field | Type | Description |
|---|---|---|
statement_typerequired | string | income_statement | balance_sheet | cash_flow_statement | equity_statement |
tickeroptional | string | Company ticker (required on shared-repo graphs, ignored otherwise) |
report_idoptional | string | Specific report identifier. If omitted, auto-resolves latest by ticker + filters. |
fiscal_yearoptional | integer | Filter by fiscal year focus when auto-resolving the report |
period_typeoptional | string | annual | quarterly | instant |
limitoptional | integer | Default: |
Example request
curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/financial-statement-analysis" \
-H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
-H "Idempotency-Key: <Idempotency-Key>" \
-H "Content-Type: application/json" \
-d '{
"statement_type": "string"
}'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: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
resultoptional | FinancialStatementAnalysisResponse | Command-specific result payload FinancialStatementAnalysisResponse fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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: |
| 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 |