Response model

A successful schema-2 data tool returns three top-level blocks. Schema 2 is the default; omit schema for schema 2 and send { "schema": 1 } only for the frozen legacy wire.

stock_financials (trimmed to the wrapper)

{
  "subject": {
    "entity": { "cik": "0000320193", "name": "Apple Inc." },
    "security": { "security_id": "sec_aapl_common", "ticker": "AAPL" }
  },
  "data": { "...": "..." },
  "meta": {
    "schema_version": "2",
    "as_of": { "sec": "2026-06-26" },
    "published_at": "2026-06-26T18:42:30.172304Z",
    "last_verified_at": "2026-06-26T18:45:35.253886Z"
  }
}

subject — the resolved entity (cik, name, entity_type) and security (security_id, ticker).
data — the tool-specific payload.
meta — provenance and clocks (below).

Some discovery/catalog calls may not need a rich subject, but the schema-2 envelope still carries data and meta.

meta fields

Field	Meaning
`schema_version`	The response schema version.
`as_of.sec`	SEC knowledge cutoff — the latest date filings were ingested through.
`as_of.market`	The market clock, on price responses.
`published_at`	When this projection was built.
`last_verified_at`	When the served fundamentals were last checked against SEC.
`parser`, `policy_version`, `build`	The extraction toolchain, rule policy, and source-hash of the underlying filing.

Numeric cells

Branch on the cell shape before doing math. Compact exact value - headline fields in stock_overview use v for the exact decimal string and optional d for display:

{ "v": "112010000000", "d": "≈$112B" }

Columnar exact value - stock_financials aligns field arrays with data.periods; exact cells are decimal strings:

{
  "periods": [{ "id": "FY2025" }],
  "fields": { "revenue": ["416161000000"] }
}

Computed ratio - ratios can be plain JSON numbers:

{ "price_to_earnings": 39.46, "effective_tax_rate": { "values": [0.1561] } }

Refusal - the value could not be proven:

{ "unavailable": "not_reported", "recovery": { "action": "use_full_document" } }

Read exact magnitudes as decimal strings. Display twins (d) are approximate and display-only. Price-derived fields carry provenance such as computed_from_prices or licensed_market_data; sources and hashes appear at higher detail levels. See Units and fields.

Refusals

Whenever a value cannot be proven — a single field or a whole tool result — you get the same flat envelope, never a null, a 0, or an empty 200:

{ "unavailable": "no_match", "recovery": { "action": "disambiguate" } }

Parse defensively: before doing math on a field, check for unavailable. When it is present, keep the token if you display the field; do not retry to “get the number” because it will not appear without new source data or parameters. Resolve any token and recovery.action in the refusal_tokens catalog served by stock_reference.

Request errors

A request error is a non-2xx HTTP status — a bad key (401), a malformed body (422), or a limit (429) — and is distinct from a refused value inside a 200. See Error codes.

Get started

Guides

Agents

MCP

Reference

meta fields

Numeric cells

Refusals

Request errors

​meta fields

​Numeric cells

​Refusals

​Request errors

meta fields

Numeric cells

Refusals

Request errors