/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.

POST/api/v1/data/facts
Rate limit100 per minute

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_idintegerconditional

1–10⁹.

tickerstringconditional

Required if filing_id omitted. 1–32 characters.

form_typestring

Default 10-K, max 32.

fiscal_yearintegerconditional

Required if filing_id omitted. 1990–2100.

quarterstring

Max 4 characters.

fact_idsarray of stringrequired

Non-empty; max 500 strings; each max 128 characters.

as_of_datestring

YYYY-MM-DD, not in the future: the filing as it stood that day.

detailstring

Default "full". "light" leaves out each result's dimensional_breakdowns. See Response detail.

Response:

ticker, form_type, fiscal_year, quarter

Filing identity.

source_url_prefix

Source-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.

results

Array 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_used

ceil(deduped_fact_id_count / 5) × 10.

amendment_context

Optional; same idea as under filings when applicable.

_warnings

Optional strings (duplicate ids deduplicated, missing ids not found in the filing, ids not filed by as_of_date).

Errors:

HTTPerror_codeWhen
400DATA_FILING_QUARTER_REQUIREDSeveral filings match without a quarter; message lists available quarters. Not charged.
404DATA_FILING_NOT_FOUNDNo filing for the given id or identity. Not charged.
404DATA_FILING_NOT_YET_FILEDThe filing had not been filed by as_of_date. Not charged.
400AS_OF_DATE_UNSUPPORTED_REGIONas_of_date for a company outside the US. Not charged.
403PLAN_TIER_INSUFFICIENT_HISTORY, PLAN_TIER_INSUFFICIENT, PLAN_TIER_INSUFFICIENT_COVERAGEThe filing is outside your plan (see History truncation notice, Coverage scope notice). Not charged.
402CREDITS_INSUFFICIENTNot enough credits.
422—Validation (empty fact_ids, limits, filing selector).