> ## Documentation Index
> Fetch the complete documentation index at: https://stockcontext.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Response model

> The success envelope (subject, data, meta), the shape of a value cell, and the refusal envelope.

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.

```json title="stock_financials (trimmed to the wrapper)" theme={null}
{
  "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:

```json theme={null}
{ "v": "112010000000", "d": "≈$112B" }
```

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

```json theme={null}
{
  "periods": [{ "id": "FY2025" }],
  "fields": { "revenue": ["416161000000"] }
}
```

**Computed ratio** - ratios can be plain JSON numbers:

```json theme={null}
{ "price_to_earnings": 39.46, "effective_tax_rate": { "values": [0.1561] } }
```

**Refusal** - the value could not be proven:

```json theme={null}
{ "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](/docs/reference/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`:

```json theme={null}
{ "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](/docs/reference/error-codes).