---
title: "Sweep one input and report the winner per value"
method: POST
path: "/v1/simulate-decision"
tags: ["Data & Analytics"]
---

# Sweep one input and report the winner per value

`POST /v1/simulate-decision`

## Request

- Base URL: `https://api.rateapi.dev`
- URL: `https://api.rateapi.dev/v1/simulate-decision`
- Auth: API key in header `X-API-Key`

Sweeps one input field (credit_score, down_payment_percent, or rate_shift_bps) across a from/to/step range (max 25 steps) and reports the winning lender / APR / monthly payment at each value, plus the flip points where the winning lender changes. This route is the single source of truth; the MCP `simulate_decision` tool calls it.

**Authentication required**: Pass your API key in the `X-API-Key` header.

## Request body

- object
  - `scenario` object, required: The borrower scenario to hold fixed while one field is swept. Takes the same fields as a decision request.
    - `product_type` string, required: Loan or deposit product this applies to.
    - `state` string, required: Two-letter US state code.
    - `intent` string, required: What the borrower is trying to do — for example purchase or refinance.
    - `amount` number, required: Loan amount in US dollars.
    - `term_months` integer: Loan term in months.
    - `credit_score` integer: Borrower FICO score used to scope which offers apply.
    - `down_payment_percent` number: Down payment as a percentage of purchase price.
  - `sweep` object, required: The field to vary across the scenario, and the range to vary it over.
    - `field` 'credit_score' | 'down_payment_percent' | 'rate_shift_bps', required: Which input to sweep.
    - `from` number, required: Value to start the sweep at.
    - `to` number, required: Value to end the sweep at.
    - `step` number, required: Must be > 0. Result capped at 25 steps.

## Response `200`

Sweep grid with the winning lender per value plus flip points.

- object
  - `product_type` string: Loan or deposit product this applies to.
  - `state` string: Two-letter US state code.
  - `sweep_field` string: The input that was swept.
  - `grid` object[]: The winning offer at each swept value.
    - `value` number: The swept input at this point on the grid.
    - `best_lender` string, nullable: Credit union that wins at this value, or null when no offer qualifies.
    - `best_apr` number, nullable: APR of the winning offer at this value, or null when no offer qualifies.
    - `monthly_payment` number, nullable: Monthly principal-and-interest payment in US dollars.
  - `flip_points` object[]: The points on the grid where the winning lender changes — the thresholds worth acting on.
    - `from_value` number: Last swept value before the winner changed.
    - `to_value` number: First swept value after the winner changed.
    - `from_lender` string, nullable: Credit union that was winning before the flip, or null when none qualified.
    - `to_lender` string, nullable: Credit union that wins after the flip, or null when none qualifies.

## Other responses

- `400`: The request was malformed — a missing required field, an unparseable body, or a parameter outside its allowed range. The `error` field names what was wrong; retrying the identical request will fail identically.
- `401`: No API key, or a key that is unknown or disabled. Send it in the `X-API-Key` header. Free keys are issued instantly by POST /keys with an email address. The response carries `WWW-Authenticate` pointing at this host's protected-resource metadata, and the `RateLimit-*` headers describing the Free-tier budget a key issued now would carry (scope `anonymous`) — a rejected request spends none of it, so `Remaining` equals `Limit`.
- `429`: Quota exhausted for the current window. `Retry-After` gives the seconds to wait; `upgradeInfo` explains how to lift the cap. Retrying before the reset will fail again and still counts as a request.

---

[API](https://skmtc.dev/rateapi/apis/rate-api.md) · [All operations](https://skmtc.dev/rateapi/apis/rate-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rateapi/apis/rate-api/revisions/06a6db76995f?raw)