/data/facts
Return structured facts for one filing by fact_id. For line-item-name queries (e.g. revenue, net income) use POST /data/line-items instead.
Filing selection: supply filing_id, or ticker and fiscal_year with optional form_type (default 10-K) and quarter. Giving both, or form_type or quarter with filing_id, returns 422.
Request:
filing_idintegerconditional1–10⁹.
tickerstringconditionalRequired if filing_id omitted. 1–32 characters.
form_typestringDefault 10-K, max 32.
fiscal_yearintegerconditionalRequired if filing_id omitted. 1990–2100.
quarterstringMax 4 characters.
fact_idsarray of stringrequiredNon-empty; max 500 strings; each max 128 characters.
as_of_datestringYYYY-MM-DD, not in the future: the filing as it stood that day.
detailstringDefault "full". "light" leaves out each result's dimensional_breakdowns. See Response detail.
Response:
ticker, form_type, fiscal_year, quarterFiling identity.
source_url_prefixSource-document URL base for this filing on its regulator's platform (SEC viewer for US filings; DART, EDINET, filings.xbrl.org, cninfo for KR / JP / EU / CN). May be null. Join it with each fact's source_locator for the document URL.
resultsArray of facts (each includes concept, fact_id, optional source_locator, values, units, period fields, plus dimensions, dimensional_breakdowns and is_consolidated_total — same meaning as in POST /data/line-items). source_locator may be null or a fragment / relative path (amendments may use a ../-relative locator); callers concatenate it with source_url_prefix as-is. Amendment-affected facts also carry restated: true, filing_date (the day the current value was filed) and prior. For SEC filings prior is a list of the earlier values, newest first, the last one being the original filing's; each holds raw_value / calculated_value / unit / decimals / fact_id / source_locator / filing_date (calculated_value is the XBRL value as filed), and an entry from before the fact existed reads "previously_null" in every field but filing_date. For other filings prior is one object: the superseded value, or { "added_by_amendment": "This fact was not present in the original filing; it was added by an amendment." } for a fact the amendment added. Facts no amendment touched carry only restated: null.
credits_usedceil(deduped_fact_id_count / 5) × 10.
amendment_contextOptional; same idea as under filings when applicable.
_warningsOptional strings (duplicate ids deduplicated, missing ids not found in the filing, ids not filed by as_of_date).
Errors:
| HTTP | error_code | When |
|---|---|---|
| 400 | DATA_FILING_QUARTER_REQUIRED | Several filings match without a quarter; message lists available quarters. Not charged. |
| 404 | DATA_FILING_NOT_FOUND | No filing for the given id or identity. Not charged. |
| 404 | DATA_FILING_NOT_YET_FILED | The filing had not been filed by as_of_date. Not charged. |
| 400 | AS_OF_DATE_UNSUPPORTED_REGION | as_of_date for a company outside the US. Not charged. |
| 403 | PLAN_TIER_INSUFFICIENT_HISTORY, PLAN_TIER_INSUFFICIENT, PLAN_TIER_INSUFFICIENT_COVERAGE | The filing is outside your plan (see History truncation notice, Coverage scope notice). Not charged. |
| 402 | CREDITS_INSUFFICIENT | Not enough credits. |
| 422 | — | Validation (empty fact_ids, limits, filing selector). |