---
title: "Tax-gain harvesting room + the tax of realizing a long-term gain"
method: POST
path: "/v1/tax/gain-harvesting"
tags: ["Tax"]
---

# Tax-gain harvesting room + the tax of realizing a long-term gain

`POST /v1/tax/gain-harvesting`

## Request

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

How much long-term capital gain can be realized at 0% then 15% (gains stack on ordinary taxable income), and — given a realize_amount — the tax of realizing it: the split across the 0%/15%/20% bands, the capital-gains tax, the incremental 3.8% NIIT once MAGI crosses the §1411 threshold (supply magi), and the rate on the next gain dollar. Reuses the tax engine's LTCG breakpoints and NIIT threshold. Deterministic; not tax advice.

## Request body

- GainHarvestingRequest
  - `tax_year` integer, required: Supported tax year (2025 or 2026).
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
  - `taxable_income` number, required: Ordinary taxable income (after deductions); sets where the gain stacks.
  - `realize_amount` number: Optional long-term gain to realize → returns the realization detail.
  - `magi` number: Optional modified AGI; adds the 3.8% NIIT on the part of the gain above the §1411 threshold.

## Response `200`

Gain-harvesting room and realization tax

- GainHarvestingResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` GainHarvestingRequest
    - `tax_year` integer, required: Supported tax year (2025 or 2026).
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
    - `taxable_income` number, required: Ordinary taxable income (after deductions); sets where the gain stacks.
    - `realize_amount` number: Optional long-term gain to realize → returns the realization detail.
    - `magi` number: Optional modified AGI; adds the 3.8% NIIT on the part of the gain above the §1411 threshold.
  - `result` object
    - `ltcg_zero_room` number: Long-term gain realizable at 0%.
    - `ltcg_fifteen_room` number: Additional gain realizable at 15%.
    - `realization` object: Present only when realize_amount is supplied.
      - `amount_at_0` number
      - `amount_at_15` number
      - `amount_at_20` number
      - `ltcg_tax` number
      - `niit` number: 3.8% on the part of the gain above the NIIT threshold (present when magi is given).
      - `total_tax` number
      - `marginal_rate` number: Rate on the next gain dollar (band rate + NIIT).
  - `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)