Properties
| Name | Type | Description |
|---|---|---|
| price_attribution | object | The price source's required attribution, present only when the prices in this response come from a source that requires one (IEX HIST). |
| ticker | string | |
| cik | string | |
| company_name | string | |
| period_type | object | |
| window | integer | Max observations requested per metric |
| metrics | object | Keyed by metric_id. Missing metrics are omitted (not nulled). |
| equity_basis_absent | object | #2517: set when the filer is a POOLED INVESTMENT VEHICLE (a commodity/crypto/currency grantor trust), for which market_cap — and every multiple derived from it — has no basis. Those metric_ids are OMI |
| listing_basis_absent | object | r119: set when the issuer's primary listing is a preferred share, warrant or right rather than its common stock (its common is not listed), so that listing's price x the common share count is not a ma |
| currency_basis_absent | object | r82 (#571): set when the filer reports in a currency other than USD. The share price is USD and MetricDuck does not convert currencies, so every metric that divides the price (or the USD market cap) b |
| depositary_basis_absent | object | #2443: set when the filer is a FOREIGN PRIVATE ISSUER (or one of the few 10-K filers whose US listing is an ADS, r84), whose US listing price is quoted per ADS while its cover-page share count is in o |
| operating_kpi_withheld | object | Founder decision 2026-10-12 (r98): set when an asked id is an operating KPI that an LLM extracted from earnings releases (operating_kpi_facts: subscribers, backlog, net_interest_margin, combined_ratio |
| component_absent | object | #3071: set when a served metric's own component is absent for this filer, so the formula engine read the missing operand as 0 and stored a number built out of nothing — `roic_vs_cost_of_debt` becomes |
| pending_annual_8k | object | Reporting-gap affordance (FY only): when the latest structured FY is older than an already-released annual earnings 8-K (filed ahead of the not-yet-filed 10-K), names that 8-K so the caller can read t |
| pending_quarterly_8k | object | #1813 reporting-gap affordance (quarterly cash-flow family only — capex/net_cf_ops/fcf): when the latest structured quarter is older than an already-released quarterly earnings 8-K (filed ahead of the |
| note | object | Navigation affordance. On a complete miss (empty `metrics`): names any asked ids that are not in the served catalog (with ranked closest candidates, #2296) and points at get_ir_documents — operational |
| resolved | object | Near-miss metric_id substitutions performed (#2296), asked -> served (e.g. {'revenue': 'revenues'}). Series in `metrics` are keyed by the SERVED id. Present only when a substitution happened — the ren |
| ir_source | object | Investor-relations page (#597), a clean https:// URL from companies.ir_domain. Populated ONLY on a not-found result (empty `metrics`) AND when the company has a known ir_domain — the concrete IR point |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/metricduck-com/json-schema/metricduck-com-metrics-history-response-schema.json",
"title": "MetricsHistoryResponse",
"x-generated": "2026-11-18",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/metricduck-com-openapi.json#/components/schemas/MetricsHistoryResponse",
"properties": {
"price_attribution": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Price Attribution",
"description": "The price source's required attribution, present only when the prices in this response come from a source that requires one (IEX HIST)."
},
"ticker": {
"type": "string",
"title": "Ticker"
},
"cik": {
"type": "string",
"title": "Cik"
},
"company_name": {
"type": "string",
"title": "Company Name"
},
"period_type": {
"$ref": "#/$defs/PeriodType"
},
"window": {
"type": "integer",
"title": "Window",
"description": "Max observations requested per metric"
},
"metrics": {
"additionalProperties": {
"$ref": "#/$defs/MetricHistorySeries"
},
"type": "object",
"title": "Metrics",
"description": "Keyed by metric_id. Missing metrics are omitted (not nulled)."
},
"equity_basis_absent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Equity Basis Absent",
"description": "#2517: set when the filer is a POOLED INVESTMENT VEHICLE (a commodity/crypto/currency grantor trust), for which market_cap — and every multiple derived from it — has no basis. Those metric_ids are OMITTED from `metrics` above and named here, so an absence reads as a decision rather than as 'no data'."
},
"listing_basis_absent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Listing Basis Absent",
"description": "r119: set when the issuer's primary listing is a preferred share, warrant or right rather than its common stock (its common is not listed), so that listing's price x the common share count is not a market capitalisation. The stored market_cap and every multiple on it are OMITTED from `metrics` above and named here. Revenue, earnings and the cash-flow statement are unaffected. Distinct from `equity_basis_absent` (a pooled vehicle has no equity basis at all)."
},
"currency_basis_absent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Currency Basis Absent",
"description": "r82 (#571): set when the filer reports in a currency other than USD. The share price is USD and MetricDuck does not convert currencies, so every metric that divides the price (or the USD market cap) by the filer's own-currency figures would mix two currencies: EV, P/E, P/B, P/S, the EV multiples and the yields. Those metric_ids are OMITTED from `metrics` above and named here. market_cap itself is served, in USD."
},
"depositary_basis_absent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Depositary Basis Absent",
"description": "#2443: set when the filer is a FOREIGN PRIVATE ISSUER (or one of the few 10-K filers whose US listing is an ADS, r84), whose US listing price is quoted per ADS while its cover-page share count is in ordinary shares. The ratio between them is a per-filer fact MetricDuck does not verify, so shares x price is not a market capitalisation and every multiple built on it is withheld. Those metric_ids are OMITTED from `metrics` above and named here. Distinct from `equity_basis_absent`: a pooled vehicle has NO equity basis, an FPI has one that is UNVERIFIED — so the next step differs (the annual report's cover page or its deposit-agreement exhibit states the ADS ratio)."
},
"operating_kpi_withheld": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Operating Kpi Withheld",
"description": "Founder decision 2026-10-12 (r98): set when an asked id is an operating KPI that an LLM extracted from earnings releases (operating_kpi_facts: subscribers, backlog, net_interest_margin, combined_ratio...). A two-reader audit found 70% of those values correct, below MetricDuck's accuracy bar, so they are not served. Those metric_ids are OMITTED from `metrics` above and named here in backticks, with where the company states the figure: its earnings release, or for headcount the 10-K's Human Capital discussion. Null when no such id was asked or when SERVE_OPERATING_KPIS is on."
},
"component_absent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Component Absent",
"description": "#3071: set when a served metric's own component is absent for this filer, so the formula engine read the missing operand as 0 and stored a number built out of nothing — `roic_vs_cost_of_debt` becomes `roic - 0`, byte-identical to `roic`. Those POINTS carry a null value (the period and citation are kept); this field names the metric and the component that decided it. Rows minted before the formula was guarded keep their fabricated value until a new filing touches the period, which is why the check runs at read time. Silent for a row with no lineage: absence of evidence is not evidence of absence."
},
"pending_annual_8k": {
"anyOf": [
{
"$ref": "#/$defs/PendingAnnual8K"
},
{
"type": "null"
}
],
"description": "Reporting-gap affordance (FY only): when the latest structured FY is older than an already-released annual earnings 8-K (filed ahead of the not-yet-filed 10-K), names that 8-K so the caller can read the newer full-year figure via get_filing_section. Null otherwise."
},
"pending_quarterly_8k": {
"anyOf": [
{
"$ref": "#/$defs/PendingQuarterly8K"
},
{
"type": "null"
}
],
"description": "#1813 reporting-gap affordance (quarterly cash-flow family only — capex/net_cf_ops/fcf): when the latest structured quarter is older than an already-released quarterly earnings 8-K (filed ahead of the not-yet-filed 10-Q, whose XBRL is what populates this series), names that 8-K so the caller can read the as-released capex/OCF/FCF via get_earnings. Value-free — substitutes no value; the agent navigates. Null otherwise."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Navigation affordance. On a complete miss (empty `metrics`): names any asked ids that are not in the served catalog (with ranked closest candidates, #2296) and points at get_ir_documents — operational KPIs / forward guidance often live only in the IR earnings deck. On a partial hit it carries ONLY the catalog-miss sentence(s) for the ids that matched nothing; null when every requested metric returned."
},
"resolved": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Resolved",
"description": "Near-miss metric_id substitutions performed (#2296), asked -> served (e.g. {'revenue': 'revenues'}). Series in `metrics` are keyed by the SERVED id. Present only when a substitution happened — the renderer must state it (⛔ no silent aliasing, #2150)."
},
"ir_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Ir Source",
"description": "Investor-relations page (#597), a clean https:// URL from companies.ir_domain. Populated ONLY on a not-found result (empty `metrics`) AND when the company has a known ir_domain — the concrete IR pointer that complements `note`'s get_ir_documents nudge for operational-KPI / forward-schedule misses, which often live in the earnings DECK rather than SEC filings. Null otherwise (never fabricated)."
}
},
"type": "object",
"required": [
"ticker",
"cik",
"company_name",
"period_type",
"window"
],
"$defs": {
"MetricHistoryPoint": {
"properties": {
"period_end": {
"type": "string",
"format": "date",
"title": "Period End",
"description": "Period end date (fiscal)"
},
"value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Value",
"description": "Metric value at this period"
},
"fiscal_year": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Fiscal Year",
"description": "Fiscal year"
},
"fiscal_period": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Fiscal Period",
"description": "Fiscal period label (Q1, Q2, Q3, Q4, FY)"
},
"accession_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Accession Number",
"description": "SEC accession that sourced this value, for citation"
},
"original_accession_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Original Accession Number",
"description": "The originally-filed (pre-amendment) accession, when accession_number above cites a later restating amendment instead (#959). Null for normal (non-restated) periods."
},
"revised_after_vantage": {
"type": "boolean",
"title": "Revised After Vantage",
"description": "VANTAGE PATH ONLY. True when the period's OWN filing was amended after the requested vantage_date (a later filing of that period, e.g. a 10-K/A, restates it) — so the served value may include a revision that was NOT knowable as of that date, even though the citation correctly names a pre-vantage filing. NOT set for a later filing's comparative recast (e.g. the next 10-K's prior-year column): filing_metrics stores exactly one CURRENT version of history, so that value is served too, unflagged. For the value as known at the vantage use get_xbrl_facts pinned to the latest filing on or before it that reports the period; get_xbrl_facts(period_history=true) gives the as-originally-filed value. Always False when no vantage_date was supplied.",
"default": false
},
"currency": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Currency",
"description": "As-filed reporting currency (ISO-4217, e.g. USD/BRL) for monetary metrics; null for non-monetary metrics (ratios/percentages/counts). #728 PR-2."
},
"sec_document_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sec Document Url",
"description": "The filing document this value was tagged in (the 10-Q/10-K page that carries it), ahead of the filing index. Null when the filing has no iXBRL document on record; cite the accession's index then (D40.2)."
},
"basis_concept": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Basis Concept",
"description": "The XBRL concept this value was actually taken from, when a coalesce chain resolved to something OTHER than the concept the metric's label names (#2149) — e.g. shares_diluted served from WeightedAverageNumberOfSharesOutstandingBasic because the filer never tagged the diluted concept. \"unknown\" when the row predates lineage capture. Null when the label's own concept won, i.e. no ambiguity arose."
}
},
"type": "object",
"required": [
"period_end"
],
"title": "MetricHistoryPoint",
"description": "Single observation in a metric's time series."
},
"MetricHistorySeries": {
"properties": {
"metric_id": {
"type": "string",
"title": "Metric Id"
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Display Name",
"description": "Human-readable name from metric_definitions"
},
"unit": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Unit",
"description": "Unit (ratio, USD, percent, etc.)"
},
"points": {
"items": {
"$ref": "#/$defs/MetricHistoryPoint"
},
"type": "array",
"title": "Points",
"description": "Observations ordered by period_end DESC, capped at `window`"
},
"comparability_note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Comparability Note",
"description": "#1149: set for operating KPIs whose definition varies by industry (e.g. passenger_load_factor, gross_booking_value). Each issuer's own value is correct, but the id is NOT comparable across companies."
}
},
"type": "object",
"required": [
"metric_id"
],
"title": "MetricHistorySeries",
"description": "Time series for a single metric_id, newest-first."
},
"PendingAnnual8K": {
"properties": {
"accession_number": {
"type": "string",
"title": "Accession Number"
},
"filing_date": {
"type": "string",
"title": "Filing Date"
},
"fiscal_year": {
"type": "integer",
"title": "Fiscal Year"
}
},
"type": "object",
"required": [
"accession_number",
"filing_date",
"fiscal_year"
],
"title": "PendingAnnual8K"
},
"PendingQuarterly8K": {
"properties": {
"accession_number": {
"type": "string",
"title": "Accession Number"
},
"filing_date": {
"type": "string",
"title": "Filing Date"
},
"fiscal_year": {
"type": "integer",
"title": "Fiscal Year"
},
"fiscal_period": {
"type": "string",
"title": "Fiscal Period"
}
},
"type": "object",
"required": [
"accession_number",
"filing_date",
"fiscal_year",
"fiscal_period"
],
"title": "PendingQuarterly8K"
},
"PeriodType": {
"type": "string",
"enum": [
"Q",
"FY",
"TTM"
],
"title": "PeriodType"
}
}
}
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/metricduck-com-metrics-history-response"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.