---
title: "Room to the top of each tax bracket"
method: POST
path: "/v1/tax/bracket-room"
tags: ["Tax"]
---

# Room to the top of each tax bracket

`POST /v1/tax/bracket-room`

## Request

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

Reports how much more ordinary income fits before crossing into each higher federal bracket (room to the top of the current and each higher bracket), plus the room remaining in the 0% and 15% long-term capital gains brackets. Powers bracket-fill decisions (Roth conversions, withdrawal sequencing, gain harvesting). Uses the year-keyed federal tables. Deterministic.

## Request body

- BracketRoomRequest
  - `tax_year` integer, required: Supported: 2025, 2026.
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
  - `taxable_income` number, required: Ordinary taxable income (after deductions).

## Response `200`

Bracket room

- BracketRoomResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` BracketRoomRequest
    - `tax_year` integer, required: Supported: 2025, 2026.
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
    - `taxable_income` number, required: Ordinary taxable income (after deductions).
  - `result` object
    - `marginal_rate` number: Rate on the next ordinary dollar.
    - `ordinary_room` object[]: Bands at/above the current income with a finite top (the 37% band is omitted).
      - `rate` number
      - `top_of_bracket` number: Taxable income at the top of the band.
      - `room` number: top_of_bracket - taxable_income.
    - `ltcg_zero_room` number: Long-term gain that would be taxed at 0%.
    - `ltcg_fifteen_room` number: Additional long-term gain taxed at 15%.
  - `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)