---
title: "Retirement health-insurance costs (ACA subsidy / Medicare)"
method: POST
path: "/v1/healthcare-costs"
tags: ["Healthcare"]
---

# Retirement health-insurance costs (ACA subsidy / Medicare)

`POST /v1/healthcare-costs`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/healthcare-costs`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Before age 65, estimates the ACA premium subsidy as a function of MAGI — the hidden cost of Roth conversions and withdrawals that raise income, including the 400%-of-FPL subsidy cliff that returns in 2026. At 65+, returns the Medicare Part B cost (base + IRMAA). The benchmark premium (second-lowest Silver plan) is an input (area/age specific). 48 states + DC. Year-keyed FPL + applicable-percentage tables. Deterministic.

## Request body

- HealthcareRequest
  - `coverage_year` 2025 | 2026, required
  - `household_size` integer, required
  - `magi` number, required
  - `benchmark_annual_premium` number: Second-lowest Silver plan, annual (area/age specific).
  - `state` string: Optional 2-letter code. "AK" and "HI" use their higher poverty guidelines; any other value (or empty) uses the 48 contiguous states + DC.
  - `age` integer: 65+ switches to the Medicare line.
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh': For the Medicare IRMAA surcharge.

## Response `200`

Cost estimate

- HealthcareResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` HealthcareRequest
    - `coverage_year` 2025 | 2026, required
    - `household_size` integer, required
    - `magi` number, required
    - `benchmark_annual_premium` number: Second-lowest Silver plan, annual (area/age specific).
    - `state` string: Optional 2-letter code. "AK" and "HI" use their higher poverty guidelines; any other value (or empty) uses the 48 contiguous states + DC.
    - `age` integer: 65+ switches to the Medicare line.
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh': For the Medicare IRMAA surcharge.
  - `result` object
    - `on_medicare` boolean
    - `aca` object: Present before Medicare age.
      - `fpl_value` number: Household poverty guideline (region-specific for AK/HI).
      - `fpl_percent` number
      - `applicable_percent` number
      - `expected_annual_contribution` number
      - `subsidy` number
      - `net_annual_premium` number
      - `eligible` boolean
      - `above_cliff` boolean: At/above 400% FPL with no subsidy (2026).
    - `medicare` object: Present at/after Medicare age.
      - `part_b_base_annual` number
      - `irmaa_annual_surcharge` number
      - `total_annual` number
  - `disclaimer` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)