Schema 2 financials

stock_financials is columnar in schema 2. periods is the header; each field row aligns to that header. Schema 2 is the default. You can omit schema in new requests:

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

Measured token budgets from the committed capabilities catalog:

Call	Measured	Gate
`stock_financials_income`	579	1,000
`stock_financials_quarterly_income`	810	1,100
`stock_financials_ytd_income`	627	1,000
`stock_financials_quarterly_cash_flow`	454	900
`stock_financials_three_statement`	1,526	2,400

Single statement vs `statements`

A single requested statement is flattened: data.statement, data.periods, data.fields, and data.unavailable_fields live directly under data. When you request more than one statement, data carries shared subject-level metadata plus a statements map. Each key (income_statement, balance_sheet, cash_flow) contains the same columnar shape a single-statement call would have:

{
  "data": {
    "shape": "operating_company",
    "statements": {
      "income_statement": { "periods": [{ "id": "FY2025" }], "fields": { "revenue": ["416161000000"] } },
      "balance_sheet": { "periods": [{ "id": "FY2025" }], "fields": { "total_assets": ["359241000000"] } }
    }
  }
}

Write parsers that branch on data.statements: if present, iterate its blocks; if absent, parse data as the one statement block.

Annual columnar shape

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

{
  "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"],
      "dividends_per_share": ["1.02", { "unavailable": "not_reported" }, { "unavailable": "not_reported" }],
      "effective_tax_rate": {
        "derived": "income_tax_expense / pretax_income",
        "values": [0.1561, 0.2409, 0.1472]
      }
    },
    "unavailable_fields": {
      "interest_expense": {
        "unavailable": "not_reported",
        "recovery": { "action": "use_full_document", "accession": "0000320193-25-000079" }
      }
    },
    "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.

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

Trimmed from tests/fixtures/render_v2/golden_aapl_quarterly_income_core.wire.json.

{
  "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": "Q1FY2026",
        "start": "2025-09-28",
        "end": "2025-12-27",
        "restated": false,
        "source": { "form": "10-Q", "accession": "0000320193-26-000006", "filed": "2026-01-30" }
      },
      {
        "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", "143756000000", "102466000000", "94036000000", "95359000000"],
      "net_income": ["26800000000", "42097000000", "27466000000", "23434000000", "24780000000"],
      "eps_diluted": ["1.80", "2.84", "1.85", "1.57", "1.65"]
    }
  },
  "meta": { "schema_version": "2", "as_of": { "sec": "2026-05-01" } }
}

Schema 2’s default quarterly window is five discrete quarters: latest + four prior. That puts the same fiscal quarter from a year ago at index 4 when all five retained quarters are available. 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.

curl -sS "https://api.stockcontext.com/v1/tools/stock_financials" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"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.

{
  "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.

{
  "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": "supply_params", "params": { "period_kind": "ytd" } }
      },
      "free_cash_flow": {
        "unavailable": "prior_quarter_filing_unavailable",
        "recovery": { "action": "supply_params", "params": { "period_kind": "ytd" } }
      }
    }
  }
}

API reference

Schema 2

Schema 1 frozen legacy

Discovery

Financials

Market data

Filings & activity

Single statement vs `statements`

Annual columnar shape

Quarterly IDs

YTD IDs

Refusals inside statement rows

​Single statement vs statements

​Annual columnar shape

​Quarterly IDs

​YTD IDs

​Refusals inside statement rows

Single statement vs `statements`

Annual columnar shape

Quarterly IDs

YTD IDs

Refusals inside statement rows