Docs
PricingSupportSign Up

Response conventions

The /metric/* endpoints require the Starter plan or higher; Free callers receive 403 PLAN_TIER_INSUFFICIENT (see API key, account, and plan errors). The formula_override request field is additionally gated to the Pro plan or higher — Starter callers must omit formula_override.

Every metric returned by /metric/* endpoints carries a status field and a derivation field. The rest of the object's contents depend on these two.

#status

ValueMeaning
okMetric was computed; value is set.
not_applicableMetric does not apply to this filing. Carries a reason string; value is null.
missing_inputA required XBRL fact is missing. Carries a missing_symbols list; value is null.
needs_price_dataPrice-sensitive metric called without current_price. value is null; pass current_price to upgrade to ok.
needs_user_formulaThe filing uses a non-standard concept combination. Pass accept_suggested_formula=true or supply formula_override to compute. value is null; a suggested_formula field is included.
needs_historyA prior-period value is required (e.g. growth rates) but is not available for this filing. value is null.
divide_by_zeroDenominator was zero. value is null.
eval_errorFormula execution failed. value is null.

not_applicable takes precedence over every other status — once an NA rule fires for a metric, the response will be not_applicable regardless of what would otherwise apply.

#derivation

ValueMeaning
derivedComputed from multiple XBRL facts via the standard formula.
as_reportedSingle XBRL fact taken at face value, no formula run.
compositeBuilt from multiple non-standard concepts (e.g. REIT CapEx = REInvestment + Maintenance).
segment_sumNo consolidated total in the filing; summed across segment members.
class_sumSummed across asset / liability class members.
company_overrideA company-specific override rule produced the value.
proxy_substitutedA proxy fact was used in place of the primary one (most often on ADR / foreign-issuer price-sensitive metrics).
TTM_rollforwardA trailing-12-month value for a quarterly filing. Comparable to annual filings of the same metric without further adjustment.
user_formula_acceptedResult of accept_suggested_formula=true — the returned suggested_formula was applied.
user_formula_customResult of a caller-supplied formula_override.
user_must_computeCompanion to status="needs_user_formula". A caller-provided calculation is required.
not_applicableCompanion to status="not_applicable".

When a metric cannot be computed, derivation repeats its status (for example missing_input or needs_price_data). Branch on status first.

#editable

ValueMeaning
trueformula_override applies to this metric.
falseformula_override does not apply to this metric.

#Currency and FX

A metric object may carry these three currency-related fields:

unit

Display unit. Either a currency code (usd, eur, twd, …) for absolute monetary metrics, or ratio / percent / days / shares etc. for non-monetary metrics.

currency

Source currency for absolute monetary metrics. Absent on ratio / percent / unitless metrics.

fx_required

true when the metric is denominated in a non-USD currency (caller may want to convert to USD before using the value). false when no conversion is needed (already USD, or unitless).

For price-sensitive metrics on foreign-issuer filings (20-F / 40-F whose reporting_currency is not USD), the metric object also carries a price_used block:

close

The price actually used in the formula (in the filer's reporting currency).

date

Date of close.

source

Identifier for the source of the price used.

original_adr_price_usd

The USD ADR price supplied (or filing-date USD price).

adr_ratio

ADR ratio (number of common shares per ADR).

fx_rate_local_per_usd

Conversion factor used for the period (filing-date price blocks).

reporting_ccy

Filer's reporting currency (e.g. EUR, TWD, CAD).

To convert a foreign-issuer absolute metric to USD:

Formula
value_usd = value / fx_rate_local_per_usd

For USD-reporting filings, fx_required is false, currency (when present) is usd, and price_used contains only close, date, source.

#Light and minimal views

Every /metric/* endpoint except POST /metric/filings accepts detail (Response detail).

  • "light" leaves out each metric's components, and the valuation_context (query_context on POST /metric/historical) echo.
  • "minimal" keeps each metric's value, unit, currency, period_basis, adjusted_value and concept_variant; status, reason and error when status is not ok; missing_symbols when status is missing_input; derivation when status is ok and it is not as_reported or derived; and the date of price_used.