Docs
PricingSupportSign Up

/metric/historical

Return metrics for many periods (quarterly or annual) for one ticker, paginated. Price-sensitive values use filing-date figures only (no live market refresh).

POST/api/v1/metric/historical
Rate limit60 per minute

Request:

tickerstring

Required. 1–32 characters.

period_typestring

Either quarterly or annual. annual covers 10-K plus the foreign-issuer annual reports 20-F and 40-F; quarterly covers 10-Q only (foreign issuers have no quarterly counterpart).

Default quarterly

start_period_startstring

Optional filter: period start ISO date (YYYY-MM-DD).

Default null

end_period_endstring

Optional filter: same date rules.

Default null

metric_namesarray

If omitted or null, all metrics returned for each period; if set, only those names from the catalog. Max 100 names.

Default null

as_of_datestring

Same meaning as /metric/all.

Default null

accept_suggested_formulaboolean

Default false

formula_overrideobject

Same structure rules as /metric/all (including ≤ 50 concepts per metric).

Default null

sortstring

period_end_asc or period_end_desc.

Default period_end_asc

pageinteger

Page index, 1–10⁶.

Default 1

page_sizeinteger

1–5 (maximum page size).

Default 3

detailstring

Same as POST /metric/all, applied to every periods[*]. See Light and minimal views.

Default "full"

Credits: 55 (base) + 148 × (number of filing rows on the current page). If the base debit succeeds but the per-row debit fails, you receive 402 with credits_used: 55, every matching filing in metric_groups (same shape as POST /metric/filings, not paged) and company.

Response:

page, page_size, total_items, has_more, next_page

Paging; next_page is null on the last page.

credits_used

Number of credits deducted for this request.

ticker

The company's symbol.

query_context

Echo of the request parameters used for the query.

periods

Array of period objects. Each includes filing metadata (including source_url_prefix per period, may be null), price_insensitive_metrics, price_sensitive_metrics (each a map of metric name to metric object, at the filing-date price), and optional root meta fields. Within each metric object, fact_refs / components entries that expose fact_id also expose source_locator (may be null). Each period may carry its own corporate_actions field, an amended flag (true when that period's filing had a merged amendment), and per-metric split variants as described in POST /metric/all; when comparing a per-share metric across periods that straddle a split, use adjusted_value instead of raw value.

_warnings

Optional; warnings about amendments or formulas.

Errors:

HTTPerror_codeWhen
400METRIC_INVALID_METRIC_NAMEA name in metric_names is outside the catalog; detail lists every supported name in _supported_metric_names. Not charged.
400METRIC_INVALID_METRIC_NAMEA returned period lacks a requested name. Charged (detail.credits_used).
400METRICS_UNSUPPORTED_FOR_KR, _JP, _EU, _CNThe ticker is a Korean, Japanese, European or China A-share company (not charged).
403PLAN_TIER_INSUFFICIENT_FORMULA_OVERRIDEformula_override below the Pro plan (not charged).
403PLAN_TIER_INSUFFICIENT_COVERAGEThe company is outside your plan's coverage scope (not charged).
402CREDITS_INSUFFICIENTInsufficient credits for base or per-row charges.
404METRIC_SUMMARY_OBJECT_MISSINGThe metrics summary could not be retrieved. Charged (detail.credits_used).
500METRIC_SUMMARY_INVALID_FORMATThe metrics summary data is invalid. Charged (detail.credits_used).
409METRIC_FORMULA_OVERRIDE_INVALIDInvalid formula_override. Charged (detail.credits_used).
422METRIC_FORMULA_APPLY_FAILEDFormula application failed. Charged (detail.credits_used).
422VALIDATION_ERRORValidation (period_type, sort, limits).