---
title: "Retirement Plans"
method: GET
path: "/api/footnotes/retirement-plans"
tags: ["Footnotes"]
---

# Retirement Plans

`GET /api/footnotes/retirement-plans`

![Pro](https://img.shields.io/badge/Pro-8b5cf6)

Returns defined-benefit pension and other-postretirement (OPEB) disclosures from the benefits footnote: funded status, benefit obligation, cost components, employer contributions, discount-rate assumptions, and the plan-asset book with asset categories cross-tabbed by fair-value level (Level 1 / 2 / 3 / NAV).

Each period entry carries one object per **plan bucket**, the `(type, location)` grid the filer disclosed: pension vs postretirement vs supplemental, US vs foreign vs a specific country. Buckets the filer left untagged appear with `type`/`location` null (the all-plans rollup). Raw axis members ride along in `typeMembers`/`locationMembers`; the plan-asset book nests under `planAssets.byCategory` with per-level amounts plus actual and target allocation shares.

`fundedStatus` is the filer's tagged figure when present; otherwise it is derived as `planAssets.total − benefitObligation` (same bucket, one currency) and flagged `fundedStatusDerived: true`.

Monetary values default to **US dollars** (`currency` parameter as on the statements endpoints: balances at the period-end spot rate, cost/contribution flows at the period-average rate, `fx` audit block, `currency=original` for as-filed). Rates and allocation shares are fractions of 1 and never converted.

**What this data can tell you:**
- Funded status: over- or under-funded, per plan bucket.
- Sensitivity to actuarial assumptions (discount rates, expected return vs actual return).
- Level 3 share of plan assets.
- Pension cost trend in earnings (service and interest components).

**Data honesty notes:**
- The full footnote is an annual (10-K) disclosure; quarterly entries carry the cost components 10-Qs tag plus year-end balances as Q4.
- Plan-NAME breakdowns (e.g. individual multiemployer plans) are not served in this version: the grid is type × location.
- Mis-tagged whole-percent rates/allocations are re-scaled and flagged `normalized: true`.
- Coverage is US-GAAP filers with defined-benefit plans (~28% of the active universe: most younger companies have none).

## Query parameters

- `symbol` string
- `cik` integer
- `cusip` string
- `composite_figi` string
- `share_class_figi` string
- `currency` string
- `period` 'annual' | 'quarter' — Base reporting period: `annual` or `quarter` (the periods companies actually report, without the derived `ttm` rollup).
- `limit` integer

## Response `200`

Defined-benefit plan disclosures by (type, location) bucket, organized by period

- object[]
  - `period` string, date — The fiscal period end date (YYYY-MM-DD)
  - `fiscalYear` integer — The company's fiscal year (handles non-December year-ends).
  - `fiscalPeriod` 'FY' | 'Q1' | 'Q2' | 'Q3' | 'Q4' — Fiscal period of a reported value: `FY` (annual) or `Q1`-`Q4` (quarterly).
  - `plans` object[] — One entry per disclosed (type, location) bucket, sorted by benefit obligation descending. Fields the filer did not tag are omitted.
    - `type` 'pension' | 'postretirement' | 'supplemental' | 'other' | 'null', nullable — Plan-type category derived from the plan-type axis member; null when untagged (the all-plans rollup).
    - `location` string, nullable — `US`, `foreign`, a specific ISO 3166-1 country code (`GB`, `JP`) when the filer tagged one, `other`, or null when untagged.
    - `typeMembers` string[] — Raw plan-type axis member QNames observed in this bucket.
    - `locationMembers` string[]
    - `currency` string, nullable — Currency of the plan-level monetary values after conversion; null when mixed (see `fx.unconverted`)
    - `normalized` boolean — Only present (as `true`) when a rate or allocation was re-scaled from a mis-tagged whole percent.
    - `benefitObligation` number — Projected/accumulated benefit obligation at period end
    - `fundedStatus` number — Plan assets minus obligation. Tagged by the filer when available; otherwise derived (see `fundedStatusDerived`).
    - `fundedStatusDerived` boolean — Only present (as `true`) when `fundedStatus` was computed as planAssets.total − benefitObligation rather than tagged.
    - `employerContributions` number — Employer contributions during the period (flow)
    - `netPeriodicCost` number — Net periodic benefit cost for the period (flow)
    - `actualReturn` number — Actual return on plan assets for the period (flow)
    - `planAssets` object — The plan-asset book.
      - `total` number — Fair value of plan assets at period end (bucket total)
      - `byCategory` object[] — Asset categories cross-tabbed by fair-value level, sorted by size.
        - `member` string — Raw XBRL member QName of the asset category
        - `name` string — Derived display label
        - `currency` string, nullable
        - `normalized` boolean
        - `total` number — Category total (tagged without a level)
        - `level1` number — Level 1 (quoted prices)
        - `level2` number — Level 2 (observable inputs)
        - `level3` number — Level 3 (unobservable inputs)
        - `nav` number — Measured at net asset value as a practical expedient
        - `allocation` number — Actual weighted-average allocation share of this category (fraction of 1)
        - `targetAllocation` number — Target allocation share (fraction of 1)
    - `cost` object — Net-periodic-cost components (flows).
      - `service` number — Service cost
      - `interest` number — Interest cost
      - `expectedReturn` number — Expected return on plan assets (income component, usually positive as filed)
      - `lossAmortization` number — Amortization of actuarial gains/losses
      - `priorServiceAmortization` number — Amortization of prior service cost/credit
    - `assumptions` object — Weighted-average assumptions as fractions of 1.
      - `discountRateBenefitObligation` number — Discount rate used for the benefit obligation
      - `discountRateNetPeriodicCost` number — Discount rate used for net periodic cost
      - `expectedReturnRate` number — Expected long-term return on plan assets
  - `dateFiled` string, date, nullable — SEC filing acceptance date of the newest filing contributing to this period. Use this to gate point-in-time data and avoid lookahead bias.
  - `fx` FxConversion — Foreign-currency conversion audit for this period. Every monetary value in `facts` is in the requested `currency` (default **US dollars**). This block is absent when the period was already wholly in the target currency (e.g. a US filer with the default USD, nothing to convert). It is present when one or more line items were originally filed in a different currency and converted on the fly, and it records the exact rate(s) applied so the conversion can be reproduced. Rates come from the Frankfurter API (api.frankfurter.dev). Instant balance-sheet items use the spot rate at period end; flow income/cash-flow items use the day-weighted average rate over the period.
    - `targetCurrency` string, required — The currency (ISO 4217) every `facts` value was converted INTO, the value of the request `currency` parameter (default USD). The literal `original` here means no conversion was requested: each fact stays in its as-reported currency (see `unconverted` for the per-fact mapping).
    - `originalCurrencies` string[], required — Every source currency (ISO 4217) that appeared in this period, the union of converted, unconverted, and already-in-target. The target currency itself is listed when some facts were natively in it (e.g. a foreign filer reporting some lines in USD alongside its converted local currency), so a mixed period reflects its true composition rather than appearing wholly converted.
    - `rates` object[], required — One entry per (source currency, method) actually applied. `rate` is the multiplier: `target = original * rate`.
      - `from` string, required — ISO 4217 source currency that was converted.
      - `method` 'spot' | 'average', required — `spot` for instant balance-sheet items (rate at period end); `average` for flow income/cash-flow items (day-weighted mean over the period).
      - `rate` number, required — Multiply the original-currency amount by this to get the `targetCurrency` amount.
      - `effectiveDate` string, date — Spot only: the date (YYYY-MM-DD) the applied rate was published (≤ period end).
      - `start` string, date — Average only: period start (YYYY-MM-DD).
      - `end` string, date — Average only: period end (YYYY-MM-DD).
    - `unconverted` object — Facts that could NOT be converted (no published rate within tolerance, or an unsupported code/date), grouped by the currency they remain in: each key is a source ISO 4217 code, each value lists the curated fact names in `facts` still in that currency (NOT `targetCurrency`). Absent when everything converted. Use it to know exactly which figures to treat as native currency.

## Other responses

- `400` — Invalid parameters or symbol not found
- `403` — Feature not available on current plan

## Changes

- **2026-08-24** `5ab763e6f203` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/stockfit/apis/stockfit-api/changes/api/footnotes/retirement-plans/get.md)

---

[API](https://skmtc.dev/stockfit/apis/stockfit-api.md) · [All operations](https://skmtc.dev/stockfit/apis/stockfit-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stockfit/stockfit-api/revisions/256933c2bdd2/schema)