---
title: "Effective-marginal-rate map (tax topography)"
method: POST
path: "/v1/tax/marginal-map"
tags: ["Tax"]
---

# Effective-marginal-rate map (tax topography)

`POST /v1/tax/marginal-map`

## Request

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

Sweeps one income variable and plots the TRUE marginal rate on the next dollar across the range, surfacing the Social Security tax torpedo, IRMAA cliffs, the ACA 400%-of-FPL subsidy cliff, NIIT, and LTCG 0/15/20 stacking in one curve. A pure composite of the tax, sstax, irmaa, and healthcare engines: at each grid point it totals the annual cost (income tax + NIIT + Additional Medicare + optional IRMAA surcharge + optional ACA net premium) and forward-differences it. Each point's marginal rate is split into additive components (ordinary, ss_inclusion, ltcg, niit, irmaa_step, aca_step), and discrete cliffs (IRMAA tiers, the ACA cliff) are reported separately. Deterministic; not tax advice.

## Request body

- MarginalMapRequest
  - `tax_year` integer, required
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
  - `ordinary_income` number: Base ordinary income held fixed (pensions, IRA distributions, wages, taxable interest).
  - `social_security_benefits` number: Gross annual Social Security (drives the §86 torpedo).
  - `qualified_income` number: LTCG + qualified dividends (also approximates net investment income for NIIT).
  - `tax_exempt_interest` number: Muni interest; added back into §86 provisional income and into MAGI.
  - `sweep_variable` 'ordinary' | 'ltcg': Which income component the swept dollars add to.
  - `sweep_start` number, required
  - `sweep_stop` number, required: Must exceed sweep_start.
  - `sweep_step` number, required: > 0. The grid is (stop−start)/step + 1 points (max 1000).
  - `include_irmaa` boolean: Add the Medicare Part B/D IRMAA surcharge. IRMAA is assessed on a 2-year MAGI lookback; the map shows the surcharge this MAGI triggers under the tax_year schedule.
  - `medicare_beneficiaries` 1 | 2: Scales the per-beneficiary IRMAA surcharge (2 = a couple both enrolled).
  - `include_aca` boolean: Add the ACA premium-tax-credit net premium (pre-65 context).
  - `household_size` integer: Required when include_aca.
  - `benchmark_annual_premium` number: Second-lowest-cost Silver plan, annual; required when include_aca.
  - `state` string: FPL region for ACA: "AK" / "HI", or empty for the 48 contiguous states + DC.

## Response `200`

The marginal-rate curve + cliff locations

- MarginalMapResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` MarginalMapRequest
    - `tax_year` integer, required
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
    - `ordinary_income` number: Base ordinary income held fixed (pensions, IRA distributions, wages, taxable interest).
    - `social_security_benefits` number: Gross annual Social Security (drives the §86 torpedo).
    - `qualified_income` number: LTCG + qualified dividends (also approximates net investment income for NIIT).
    - `tax_exempt_interest` number: Muni interest; added back into §86 provisional income and into MAGI.
    - `sweep_variable` 'ordinary' | 'ltcg': Which income component the swept dollars add to.
    - `sweep_start` number, required
    - `sweep_stop` number, required: Must exceed sweep_start.
    - `sweep_step` number, required: > 0. The grid is (stop−start)/step + 1 points (max 1000).
    - `include_irmaa` boolean: Add the Medicare Part B/D IRMAA surcharge. IRMAA is assessed on a 2-year MAGI lookback; the map shows the surcharge this MAGI triggers under the tax_year schedule.
    - `medicare_beneficiaries` 1 | 2: Scales the per-beneficiary IRMAA surcharge (2 = a couple both enrolled).
    - `include_aca` boolean: Add the ACA premium-tax-credit net premium (pre-65 context).
    - `household_size` integer: Required when include_aca.
    - `benchmark_annual_premium` number: Second-lowest-cost Silver plan, annual; required when include_aca.
    - `state` string: FPL region for ACA: "AK" / "HI", or empty for the 48 contiguous states + DC.
  - `result` object
    - `points` object[]: One entry per grid point along the swept variable.
      - `income` number: Swept-variable level (sweep_start + i·step).
      - `agi` number: Resulting adjusted gross income.
      - `marginal_rate` number: True marginal rate on the next dollar of the swept variable.
      - `total_cost` number: Total annual cost C (income tax + NIIT + Additional Medicare + IRMAA + ACA net premium).
      - `components` object: Additive breakdown of marginal_rate (the parts sum to it).
        - `ordinary` number: Ordinary bracket rate on the swept dollar.
        - `ss_inclusion` number: §86 torpedo: extra ordinary tax from more Social Security becoming taxable.
        - `ltcg` number: LTCG / qualified-dividend rate (0/15/20 stacking).
        - `niit` number: 3.8% NIIT + 0.9% Additional Medicare.
        - `irmaa_step` number: Amortized IRMAA surcharge change (spikes at a tier crossing).
        - `aca_step` number: Amortized ACA subsidy change (spikes at the 400%-FPL cliff).
    - `cliffs` object[]: Discrete discontinuities — IRMAA tier crossings and the ACA 400%-FPL subsidy cliff.
      - `income` number: Swept-variable level just past the cliff (located within one step).
      - `kind` 'irmaa' | 'aca'
      - `annual_jump` number: Discrete annual dollars added at the cliff.
  - `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)