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

# Schema 2 financials

> Columnar annual, quarterly, YTD, and derived-Q4 financial statement examples for schema 2.

`stock_financials` is columnar in schema 2. `periods` is the header; each field row aligns to that header.

Schema 2 is not the default yet. Send `"schema": 2` explicitly:

```bash theme={null}
curl -sS "https://api.stockcontext.com/v1/tools/stock_financials" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema":2,"symbol":"AAPL","statements":["income"],"periods":3,"detail":"core"}'
```

Measured token budgets from the committed capabilities catalog:

| Call                                   | Measured |  Gate |
| -------------------------------------- | -------: | ----: |
| `stock_financials_income`              |      514 | 1,000 |
| `stock_financials_quarterly_income`    |      646 | 1,100 |
| `stock_financials_ytd_income`          |      553 | 1,000 |
| `stock_financials_quarterly_cash_flow` |      457 |   900 |
| `stock_financials_three_statement`     |    1,414 | 2,400 |

## Annual columnar shape

Trimmed from `tests/fixtures/render_v2/golden_aapl_income_core.wire.json`; shown values are unchanged.

```json theme={null}
{
  "subject": {
    "entity": { "cik": "0000320193", "name": "Apple Inc.", "shape": "operating_company" },
    "security": { "security_id": "sec_0000320193_aapl", "ticker": "AAPL" }
  },
  "data": {
    "statement": "income_statement",
    "shape": "operating_company",
    "periods": [
      { "id": "FY2025", "start": "2024-09-29", "end": "2025-09-27", "restated": false },
      { "id": "FY2024", "start": "2023-10-01", "end": "2024-09-28", "restated": false },
      { "id": "FY2023", "start": "2022-09-25", "end": "2023-09-30", "restated": false }
    ],
    "source": { "form": "10-K", "accession": "0000320193-25-000079", "filed": "2025-10-31" },
    "reporting": { "period_kind": "annual", "vintage": "latest_restated", "reporting_currency": "USD" },
    "fields": {
      "revenue": ["416161000000", "391035000000", "383285000000"],
      "net_income": ["112010000000", "93736000000", "96995000000"],
      "eps_diluted": ["7.46", "6.08", "6.13"],
      "effective_tax_rate": {
        "derived": "income_tax_expense / pretax_income",
        "values": [0.1561, 0.2409, 0.1472]
      }
    },
    "periods_available": 3
  },
  "meta": {
    "schema_version": "2",
    "policy_version": "2026-06-18",
    "as_of": { "sec": "2026-06-26" },
    "published_at": "2026-06-26T18:42:30.172304Z"
  }
}
```

## Quarterly IDs

Quarter IDs come from the filer's DEI fiscal period and year, not the calendar quarter. AAPL's fiscal Q2 FY2026 ended on `2026-03-28`.

```bash theme={null}
curl -sS "https://api.stockcontext.com/v1/tools/stock_financials" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema":2,"symbol":"AAPL","statements":["income"],"period_kind":"quarter","periods":4}'
```

Trimmed from `tests/fixtures/render_v2/golden_aapl_quarterly_income_core.wire.json`; shown values are unchanged.

```json theme={null}
{
  "data": {
    "statement": "income_statement",
    "periods": [
      {
        "id": "Q2FY2026",
        "start": "2025-12-28",
        "end": "2026-03-28",
        "restated": false,
        "source": { "form": "10-Q", "accession": "0000320193-26-000042", "filed": "2026-05-01" }
      },
      {
        "id": "Q4FY2025",
        "start": "2025-06-29",
        "end": "2025-09-27",
        "restated": false,
        "derived": "fy_minus_ytd_q3",
        "source": { "form": "10-Q", "accession": "0000320193-25-000079", "filed": "2025-10-31" }
      },
      {
        "id": "Q3FY2025",
        "start": "2025-03-30",
        "end": "2025-06-28",
        "restated": false,
        "source": { "form": "10-Q", "accession": "0000320193-25-000071", "filed": "2025-08-01" }
      },
      {
        "id": "Q2FY2025",
        "start": "2024-12-29",
        "end": "2025-03-29",
        "restated": false,
        "source": { "form": "10-Q", "accession": "0000320193-25-000033", "filed": "2025-05-02" }
      }
    ],
    "reporting": { "period_kind": "quarter", "vintage": "latest_restated", "reporting_currency": "USD" },
    "fields": {
      "revenue": ["105200000000", "102466000000", "94036000000", "95359000000"],
      "net_income": ["26800000000", "27466000000", "23434000000", "24780000000"],
      "eps_diluted": ["1.80", "1.85", "1.57", "1.65"]
    }
  },
  "meta": { "schema_version": "2", "as_of": { "sec": "2026-05-01" } }
}
```

The `Q4FY2025` column is derived from `FY - YTD_Q3`. The period-level marker `derived: "fy_minus_ytd_q3"` means the column is not a filer-tagged discrete quarter.

## YTD IDs

YTD periods use `YTDkFYyyyy`, where `k` is the quarter ordinal included in the cumulative period.

```bash theme={null}
curl -sS "https://api.stockcontext.com/v1/tools/stock_financials" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema":2,"symbol":"AAPL","statements":["income"],"period_kind":"ytd","periods":3}'
```

Trimmed from `tests/fixtures/render_v2/golden_aapl_ytd_income_core.wire.json`; shown values are unchanged.

```json theme={null}
{
  "data": {
    "statement": "income_statement",
    "periods": [
      { "id": "YTD2FY2026", "start": "2025-09-28", "end": "2026-03-28", "restated": false },
      { "id": "YTD3FY2025", "start": "2024-09-29", "end": "2025-06-28", "restated": false },
      { "id": "YTD2FY2025", "start": "2024-09-29", "end": "2025-03-29", "restated": false }
    ],
    "reporting": { "period_kind": "ytd", "vintage": "latest_restated", "reporting_currency": "USD" },
    "fields": {
      "revenue": ["220000000000", "313695000000", "219659000000"],
      "net_income": ["55000000000", "75680000000", "52246000000"],
      "eps_diluted": ["3.70", "5.05", "3.48"]
    }
  },
  "meta": { "schema_version": "2", "as_of": { "sec": "2026-05-01" } }
}
```

## Refusals inside statement rows

If a field cannot be proven for the requested period, schema 2 refuses at the narrowest honest altitude.

Trimmed from `tests/fixtures/render_v2/golden_aapl_quarterly_cash_flow_recovery_core.wire.json`; shown values are unchanged.

```json theme={null}
{
  "data": {
    "statement": "cash_flow",
    "periods": [{ "id": "Q3FY2025", "start": "2025-03-30", "end": "2025-06-28", "restated": false }],
    "fields": {
      "capex": ["1100000000"],
      "share_based_comp": ["1200000000"],
      "depreciation_amortization": ["1300000000"]
    },
    "unavailable_fields": {
      "operating_cash_flow": {
        "unavailable": "prior_quarter_filing_unavailable",
        "recovery": { "action": "use_alternative_field", "field": "operating_cash_flow" }
      },
      "free_cash_flow": {
        "unavailable": "prior_quarter_filing_unavailable",
        "recovery": { "action": "use_alternative_field", "field": "free_cash_flow" }
      }
    }
  }
}
```