How should an AI agent or app handle missing SEC financial data?
The single most likely integration bug: silently treating a MISSING metric as zero. That would misrepresent a real company's finances. Here is the real example and the correct fix.
Direct answer
Never coerce a missing value to 0or an estimate. Check the field’s status first (AVAILABLE, MISSING, or LINEAGE_MISSING) and branch explicitly — treat anything other than AVAILABLE as unknown, not zero.
Why missing data is not zero
A company can legitimately not file the XBRL concept a metric depends on. Reporting that as 0would state, incorrectly, that the company has none of that line item — a materially false financial claim. LedgerBase instead reports the field as explicitly missing, so a consumer knows the difference between “zero” and “unknown.”
The four data states
| Status | Meaning |
|---|---|
AVAILABLE | Present with verified SEC/XBRL lineage — a direct or derived value. |
MISSING | No safe SEC-backed value exists. Not zero — unknown. |
LINEAGE_MISSING | A value exists but lineage cannot be confirmed — ambiguous, and not ready for automated use without manual verification. |
A real example: AMZN total liabilities
curl -H "X-API-Key: $LEDGERBASE_API_KEY" https://api.ledgerbase.cc/v1/companies/AMZN/data-quality{
"overallStatus": "OK_WITH_MISSING_METRICS",
"missingMetricDetails": [
{
"metricKey": "total_liabilities",
"status": "MISSING",
"reason": "Not found in ingested SEC data",
"required": true
}
]
}Amazon does not file a us-gaap:Liabilities XBRL fact, so LedgerBase reports total_liabilities as explicitly MISSING rather than guessing. This is intentional, documented behavior — a trust feature, not a defect.
How AI agents should avoid hallucinating financial values
An AI agent consuming LedgerBase data should treat a MISSING or LINEAGE_MISSINGfield as “no answer available,” and say so, rather than filling the gap from a language model’s general knowledge or interpolating from other periods. Silent estimation by an agent is exactly the failure mode this status vocabulary exists to prevent.
Recommended application-level handling
const value = detail.value ?? 0;— silently fabricates a false zero for a real company’s liabilities.if (detail.status === "MISSING") { /* treat as unknown, do not compute with it */ } — branch explicitly on status before using any value.Limitations
Status vocabulary is per-field, not global — different endpoints expose it under different field names. See the Data Quality & Lineage topic in the API reference for the authoritative glossary before integrating against a new endpoint.
Try it yourself
Run this call from the API reference’s Try It panel, inspect metric coverage in the Metric Catalog, or go back to Learn for the full interactive tutorial and related concepts.