Project several scenarios
Computes up to 25 complete federal profiles and returns each result independently, with no comparison or ranking.
Compute a SET of hypothetical federal returns — N independent results, no comparison.
Runs the full federal compute over up to 25 caller-supplied complete profiles and returns each result INDEPENDENTLY — NO deltas, NO comparison, NO ranking (any comparison is the caller's act). Federal-only. Bills PER SCENARIO (each computed/deterministic-decline slot is one billable unit; per-slot validation/compute errors and quota-cut slots are not billed). Idempotency-Key is MANDATORY (absent → 400).
Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer <API key> |
| Content-Type | Yes | application/json |
| Idempotency-Key | Yes | MANDATORY on this endpoint (unlike the single-compute endpoints): a unique value per logical request. A same-key/same-body retry replays and bills once; a changed scenario set under the same key → 409. |
Request body
| Field | Description |
|---|---|
| scenariosarray of { label?, profile } (1 to 25)required | The profiles to compute, in order. Results come back by the same index. |
| scenarios[].labelstring | Optional label echoed back on that entry. Used only in the response; never stored. |
| scenarios[].profileFederalProfilerequired | A complete federal request body, exactly as accepted by POST /tax-compute/federal. |
Every field of profile is in the federal reference.
Example
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
}
}
]
}'{
"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"
}
]
}Responses
| Status | Meaning |
|---|---|
| 200 | { workflow: 'what-if', disclaimer, legal_notice, scenario_count, results[] } — each result is a normal computed envelope OR a normal decline, by index; NO cross-scenario comparison/ranking field. |
| 400 | Invalid body / JSON / failed validation |
| 401 | Missing / unknown / revoked key (no enumeration) |
| 403 | Account suspended — contact billing (distinct from 401: the key is valid) |
| 409 | Idempotency-Key reused with a different body (`idempotency_key_reused`), or a concurrent in-flight duplicate (`idempotency_key_in_progress`). Retry; NOT billed. |
| 429 | Monthly quota exhausted (account-wide;Monthly quota exhausted (account-wide; `quota_exceeded`, next_action `upgrade_plan_or_wait_next_period`, retry_safe false) or per-minute rate exceeded (`rate_limit_exceeded`, next_action `retry_after_backoff`, retry_safe true). Not billed. |
| 500 | Sanitized server error computing the return |
| 503 | Metering outage — fail-closed (the call is NOT silently served free) |
Each entry in results carries its index, its label if you sent one, and either a normal computed result or a normal decline, with its own billed (computed results also carry a legal notice). An entry that could not run (for example, quota ran out partway) carries an error and is not billed. Guide: Project several scenarios.