Guides by outcome

Project several scenarios in one call

Send up to 25 complete federal profiles, for example this year's salary and a possible raise, and get each one computed independently in a single request.

How it works

  • Each scenario is a profile in exactly the shape of a federal request, plus an optional label that is echoed back.
  • Each result is computed on its own. A scenario can decline while the others compute; a decline says nothing about its siblings.
  • The response contains no differences, comparisons, or rankings. Comparing results is your product's decision, not the engine's.
  • Each scenario that computes or declines is billed as one call, and counts as one request against your per-minute rate.

An Idempotency-Key is required

Unlike the single-compute endpoints, what-if rejects a request without one. Reusing the key with the same scenarios replays the response and bills once.

Run three scenarios

The third scenario leaves out W-2 box 5, so it declines while the other two compute:
Request
curl https://tax-mcp.com/api/mcp/tax-compute/what-if \
  -H "Authorization: Bearer $TAX_MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "scenarios": [
      {
        "label": "current-salary",
        "profile": {
          "year": 2025,
          "filingStatus": "single",
          "canBeClaimedAsDependent": false,
          "noForeignOrTerritoryExclusionAffirmed": true,
          "wages": 90000,
          "medicareWages": 90000
        }
      },
      {
        "label": "with-raise",
        "profile": {
          "year": 2025,
          "filingStatus": "single",
          "canBeClaimedAsDependent": false,
          "noForeignOrTerritoryExclusionAffirmed": true,
          "wages": 120000,
          "medicareWages": 120000
        }
      },
      {
        "label": "raise-no-box-5",
        "profile": {
          "year": 2025,
          "filingStatus": "single",
          "canBeClaimedAsDependent": false,
          "noForeignOrTerritoryExclusionAffirmed": true,
          "wages": 120000
        }
      }
    ]
  }'
Response 200 · 2 of 3 computed
{
  "workflow": "what-if",
  "disclaimer": "<workflow disclaimer: hypothetical / not advice / not a filing / not ranked — elided>",
  "legal_notice": {
    "ref": "https://tax-mcp.com/terms#compute-notice",
    "version": "v1",
    "text": "<computation-support notice — see full response>"
  },
  "scenario_count": 3,
  "results": [
    {
      "index": 0,
      "label": "current-salary",
      "computed": true,
      "year": 2025,
      "filingStatus": "single",
      "taxableIncome": 74250,
      "incomeTax": 11255,
      "totalTax": 11255,
      "lines": [
        { "lineId": "1040:15", "label": "Taxable income", "amount": 74250 },
        {
          "lineId": "1040:16",
          "label": "Income tax",
          "amount": 11255,
          "derivation": "<5 derivation steps — see full response>"
        },
        { "lineId": "1040:24", "label": "Total tax", "amount": 11255 }
      ],
      "flags": [
        "OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
      ],
      "billed": true,
      "retry_safe": true,
      "next_action": "none",
      "provenance": {
        "engine": "deterministic",
        "jurisdiction": "what-if",
        "tax_year": 2025
      },
      "legal_notice": {
        "ref": "https://tax-mcp.com/terms#compute-notice",
        "version": "v1",
        "text": "<computation-support notice — see full response>"
      }
    },
    {
      "index": 1,
      "label": "with-raise",
      "computed": true,
      "year": 2025,
      "filingStatus": "single",
      "taxableIncome": 104250,
      "incomeTax": 17867,
      "totalTax": 17867,
      "lines": [
        { "lineId": "1040:15", "label": "Taxable income", "amount": 104250 },
        {
          "lineId": "1040:16",
          "label": "Income tax",
          "amount": 17867,
          "derivation": "<4 derivation steps — see full response>"
        },
        { "lineId": "1040:24", "label": "Total tax", "amount": 17867 }
      ],
      "flags": [
        "OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
      ],
      "billed": true,
      "retry_safe": true,
      "next_action": "none",
      "provenance": {
        "engine": "deterministic",
        "jurisdiction": "what-if",
        "tax_year": 2025
      },
      "legal_notice": {
        "ref": "https://tax-mcp.com/terms#compute-notice",
        "version": "v1",
        "text": "<computation-support notice — see full response>"
      }
    },
    {
      "index": 2,
      "label": "raise-no-box-5",
      "computed": false,
      "code": "surtax_additional_medicare",
      "reason": "box-5 Medicare wages were not supplied, but the return shows other objective W-2 evidence (positive wages) — box 5 can exceed box 1 or diverge from box 2/3/6 by an unbounded amount for real filers (401(k)/403(b)/457(b) elective deferrals reduce box 1 but remain subject to FICA/Medicare tax, inflating box 5 relative to box 1), so no finite margin can rule out the Additional Medicare Tax threshold ($200,000 for single) being crossed at box 5 — supply medicareWages to compute, or a preparer must review; computing without it could under-state tax",
      "billed": true,
      "retry_safe": false,
      "next_action": "review_inputs"
    }
  ]
}
Full response, including line derivations
{
  "workflow": "what-if",
  "disclaimer": "<workflow disclaimer: hypothetical / not advice / not a filing / not ranked — elided>",
  "legal_notice": {
    "ref": "https://tax-mcp.com/terms#compute-notice",
    "version": "v1",
    "text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
  },
  "scenario_count": 3,
  "results": [
    {
      "index": 0,
      "label": "current-salary",
      "computed": true,
      "year": 2025,
      "filingStatus": "single",
      "taxableIncome": 74250,
      "incomeTax": 11255,
      "totalTax": 11255,
      "lines": [
        {
          "lineId": "1040:15",
          "label": "Taxable income",
          "amount": 74250,
          "derivation": []
        },
        {
          "lineId": "1040:16",
          "label": "Income tax",
          "amount": 11255,
          "derivation": [
            {
              "lineId": "1040:16",
              "label": "Tax Table method (IRS-mandated below $100,000 taxable income)",
              "inputs": [
                { "name": "taxableIncome", "value": 74250 }
              ],
              "rule": {
                "description": "Form 1040 instructions require the published Tax Table — a lookup on the midpoint of a narrow taxable-income band — for taxable income under $100,000; the exact bracket formula (Tax Computation Worksheet) applies only at $100,000 or more.",
                "authority": "Form 1040 instructions — Tax Table"
              },
              "computation": "taxable income $74,250 → Tax Table band midpoint $74,275",
              "result": 0
            },
            {
              "lineId": "1040:16",
              "label": "Ordinary income tax — 10% bracket",
              "inputs": [
                { "name": "taxableIncomeInBracket", "value": 11925 }
              ],
              "rule": {
                "description": "marginal rate × taxable income falling within this bracket",
                "authority": "IRC §1(j)",
                "constantRef": {
                  "table": "BRACKETS_BY_YEAR",
                  "key": "2025/single",
                  "value": "10% (up to $11,925)",
                  "revProc": "Rev. Proc. 2024-40"
                }
              },
              "computation": "0.1 × $11,925 = $1,192.5",
              "result": 1192.5
            },
            {
              "lineId": "1040:16",
              "label": "Ordinary income tax — 12% bracket",
              "inputs": [
                { "name": "taxableIncomeInBracket", "value": 36550 }
              ],
              "rule": {
                "description": "marginal rate × taxable income falling within this bracket",
                "authority": "IRC §1(j)",
                "constantRef": {
                  "table": "BRACKETS_BY_YEAR",
                  "key": "2025/single",
                  "value": "12% (up to $48,475)",
                  "revProc": "Rev. Proc. 2024-40"
                }
              },
              "computation": "0.12 × $36,550 = $4,386",
              "result": 4386
            },
            {
              "lineId": "1040:16",
              "label": "Ordinary income tax — 22% bracket",
              "inputs": [
                { "name": "taxableIncomeInBracket", "value": 25800 }
              ],
              "rule": {
                "description": "marginal rate × taxable income falling within this bracket",
                "authority": "IRC §1(j)",
                "constantRef": {
                  "table": "BRACKETS_BY_YEAR",
                  "key": "2025/single",
                  "value": "22% (up to $103,350)",
                  "revProc": "Rev. Proc. 2024-40"
                }
              },
              "computation": "0.22 × $25,800 = $5,676",
              "result": 5676
            },
            {
              "lineId": "1040:16",
              "label": "Whole-dollar rounding — ordinary income tax",
              "inputs": [
                { "name": "unroundedOrdinaryTax", "value": 11255 }
              ],
              "rule": {
                "description": "round the ordinary income tax to whole dollars",
                "authority": "Form 1040 instructions — whole-dollar rounding"
              },
              "computation": "$11,255 − $11,254.5 = $0.5",
              "result": 0.5
            }
          ]
        },
        {
          "lineId": "1040:24",
          "label": "Total tax",
          "amount": 11255,
          "derivation": []
        }
      ],
      "flags": [
        "OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
      ],
      "billed": true,
      "retry_safe": true,
      "next_action": "none",
      "provenance": {
        "engine": "deterministic",
        "jurisdiction": "what-if",
        "tax_year": 2025
      },
      "legal_notice": {
        "ref": "https://tax-mcp.com/terms#compute-notice",
        "version": "v1",
        "text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
      }
    },
    {
      "index": 1,
      "label": "with-raise",
      "computed": true,
      "year": 2025,
      "filingStatus": "single",
      "taxableIncome": 104250,
      "incomeTax": 17867,
      "totalTax": 17867,
      "lines": [
        {
          "lineId": "1040:15",
          "label": "Taxable income",
          "amount": 104250,
          "derivation": []
        },
        {
          "lineId": "1040:16",
          "label": "Income tax",
          "amount": 17867,
          "derivation": [
            {
              "lineId": "1040:16",
              "label": "Ordinary income tax — 10% bracket",
              "inputs": [
                { "name": "taxableIncomeInBracket", "value": 11925 }
              ],
              "rule": {
                "description": "marginal rate × taxable income falling within this bracket",
                "authority": "IRC §1(j)",
                "constantRef": {
                  "table": "BRACKETS_BY_YEAR",
                  "key": "2025/single",
                  "value": "10% (up to $11,925)",
                  "revProc": "Rev. Proc. 2024-40"
                }
              },
              "computation": "0.1 × $11,925 = $1,192.5",
              "result": 1192.5
            },
            {
              "lineId": "1040:16",
              "label": "Ordinary income tax — 12% bracket",
              "inputs": [
                { "name": "taxableIncomeInBracket", "value": 36550 }
              ],
              "rule": {
                "description": "marginal rate × taxable income falling within this bracket",
                "authority": "IRC §1(j)",
                "constantRef": {
                  "table": "BRACKETS_BY_YEAR",
                  "key": "2025/single",
                  "value": "12% (up to $48,475)",
                  "revProc": "Rev. Proc. 2024-40"
                }
              },
              "computation": "0.12 × $36,550 = $4,386",
              "result": 4386
            },
            {
              "lineId": "1040:16",
              "label": "Ordinary income tax — 22% bracket",
              "inputs": [
                { "name": "taxableIncomeInBracket", "value": 54875 }
              ],
              "rule": {
                "description": "marginal rate × taxable income falling within this bracket",
                "authority": "IRC §1(j)",
                "constantRef": {
                  "table": "BRACKETS_BY_YEAR",
                  "key": "2025/single",
                  "value": "22% (up to $103,350)",
                  "revProc": "Rev. Proc. 2024-40"
                }
              },
              "computation": "0.22 × $54,875 = $12,072.5",
              "result": 12072.5
            },
            {
              "lineId": "1040:16",
              "label": "Ordinary income tax — 24% bracket",
              "inputs": [
                { "name": "taxableIncomeInBracket", "value": 900 }
              ],
              "rule": {
                "description": "marginal rate × taxable income falling within this bracket",
                "authority": "IRC §1(j)",
                "constantRef": {
                  "table": "BRACKETS_BY_YEAR",
                  "key": "2025/single",
                  "value": "24% (up to $197,300)",
                  "revProc": "Rev. Proc. 2024-40"
                }
              },
              "computation": "0.24 × $900 = $216",
              "result": 216
            }
          ]
        },
        {
          "lineId": "1040:24",
          "label": "Total tax",
          "amount": 17867,
          "derivation": []
        }
      ],
      "flags": [
        "OBBBA-2025-new-deductions-senior-bonus/tips/overtime/car-loan-NOT-evaluated-engine-cannot-verify-eligibility-from-W2/1099-preparer-must-confirm"
      ],
      "billed": true,
      "retry_safe": true,
      "next_action": "none",
      "provenance": {
        "engine": "deterministic",
        "jurisdiction": "what-if",
        "tax_year": 2025
      },
      "legal_notice": {
        "ref": "https://tax-mcp.com/terms#compute-notice",
        "version": "v1",
        "text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
      }
    },
    {
      "index": 2,
      "label": "raise-no-box-5",
      "computed": false,
      "code": "surtax_additional_medicare",
      "reason": "box-5 Medicare wages were not supplied, but the return shows other objective W-2 evidence (positive wages) — box 5 can exceed box 1 or diverge from box 2/3/6 by an unbounded amount for real filers (401(k)/403(b)/457(b) elective deferrals reduce box 1 but remain subject to FICA/Medicare tax, inflating box 5 relative to box 1), so no finite margin can rule out the Additional Medicare Tax threshold ($200,000 for single) being crossed at box 5 — supply medicareWages to compute, or a preparer must review; computing without it could under-state tax",
      "billed": true,
      "retry_safe": false,
      "next_action": "review_inputs"
    }
  ]
}

Read the results

Iterate over results by index. Each entry is a normal computed result or a normal decline, with its own billed and next_action(computed results also carry a legal notice). A slot that could not run (for example, the month's quota ran out partway) carries an error instead and is not billed.

See also: /tax-compute/what-if.

Roadmap status for this page

Generated from the roadmap (updated 2026-10-30). Shipped & certified means live and independently checked against primary tax sources; certifying means live, with those checks still in progress.

Lifecycle — projection, estimates, amendments
CapabilityStatus
What-if: up to 25 complete profiles per call, each computed on its ownComputes up to 25 complete federal what-if profiles per call, each on its own. No comparison or ranking.◐ certifying