Skip to main content
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: 
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:
CallMeasuredGate
stock_financials_income5141,000
stock_financials_quarterly_income6461,100
stock_financials_ytd_income5531,000
stock_financials_quarterly_cash_flow457900
stock_financials_three_statement1,4142,400

​
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"],
      "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. 
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. 
{
  "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. 
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. 
{
  "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": "use_alternative_field", "field": "operating_cash_flow" }
      },
      "free_cash_flow": {
        "unavailable": "prior_quarter_filing_unavailable",
        "recovery": { "action": "use_alternative_field", "field": "free_cash_flow" }
      }
    }
  }
}