Value-Retention Curve
How one model-year cohort held its asking price over 12 months, with the odometer beside it and the whole market for comparison.
This is the technical reference. For the price, a rendered sample and answers to common questions, see the Value-Retention Curve product page.
At a glance
| Price | $4.99 for one cohort; a batch is $0.99 per cohort delivered. Minimum $4.99 per run. A batch is quoted before it runs: the first call returns a total and charges nothing. |
| Tool name | generate_value_retention_curve |
| Scope | reports:value-retention-curve |
| Built for | Auto Lender, Insurance Adjuster, Market Researcher |
What it does
The value-retention curve for one model-year cohort (year, make and model, optionally trim): twelve months of sold-market data, month by month, with the units that left dealer websites, the median asking price at exit, the median odometer and the median days to sell, pinned to ONE model year so the curve moves only when values move, never when the mix of vintages moves. States the retention (the last month's median as a percent of the first), the odometer drift in miles, the low point of the window and the units, and draws the whole used market (every vehicle of the same inventory type, nationally) as a comparison line rebased to the same start. With a powertrain (e.g. BEV) the cohort is filtered to it and a combustion comparator is added: the same nameplate on combustion when it has sales, else every vehicle of the same model year on combustion, stated on the report. National by default; a US state narrows the cohort. From the Sold Summary API: a sale is inferred when a listing leaves a dealer website, every price is the advertised asking price at exit (never a negotiated transaction price), and the cars in a cohort age and add miles across the window, so it is a cohort trajectory, not same-car depreciation and not a residual forecast. PORTFOLIO RETENTION SHEET: paste cohorts instead (one per line: year make model, optional trim) and every cohort gets its own row (first and last median, retention, odometer drift, units) in one table sorted lowest retention first, with a CSV of every row and the whole-market retention beside it. Use when a lender, insurer or analyst asks how a specific model year is holding value, what residual or advance-rate cushion a cohort needs, whether an EV cohort is eroding faster than combustion, or which cohorts in a book are losing value fastest. Do NOT use to value one VIN (use Vehicle Valuation Report), to pick where to remarket units (use Remarketing Liquidity Map), or for a seasonal buy and sell timing question (use Seasonal Buy-Sell Calendar). The sold data has state grain, not ZIP or radius. PRICING: $4.99 for one cohort. A portfolio sheet is metered at $0.99 per cohort with a curve, with a $4.99 minimum, up to 200 cohorts per run; lines that cannot be read or that have no sold data are not billed. A sheet that could cost more than $4.99 requires cost confirmation: call first WITHOUT confirm_cost_usd for an up-to quote (this charges nothing), then again with confirm_cost_usd set to the quoted cap once the user approves.
Arguments
| Argument | What it is | Example | |
|---|---|---|---|
year |
Recommended | Model year of the cohort (the 2022 in "2022 Toyota Camry"). Needed for one cohort; leave blank when you paste cohorts. A curve is pinned to one model year. | 2022 |
make |
Recommended | Make (e.g. Toyota). Needed for one cohort. | Toyota |
model |
Recommended | Model (e.g. Camry). Needed for one cohort. | Camry |
trim |
Optional | Trim (e.g. XSE) to pin the cohort to one trim. Leave blank for every trim of the model. | XSE |
state |
Optional | US state, as a 2-letter code (e.g. TX), to narrow the cohort to one state. Leave blank for the national curve. The comparison line is always the whole US market. | TX |
inventory_type |
Optional | Which market: used (the default), new, or certified pre-owned. | used |
months |
Optional | Months in the curve, 2 to 12, ending at the latest data month. 12 by default. | 12 |
powertrain_type |
Optional | Filter the cohort to one powertrain (BEV, PHEV, HEV, MHEV or Combustion) and pair it against combustion: the same nameplate on combustion when it has sales, else every vehicle of the same model year on combustion. | BEV |
cohorts |
Optional | A portfolio sheet instead of one cohort: one cohort per line as "year make model" with an optional trim (e.g. "2022 Toyota Camry XSE"). Up to 200. State, inventory type and months apply to every line. Metered at $0.99 per cohort with a curve, with a $4.99 minimum. | 2022 Toyota Camry XSE |
confirm_cost_usd |
Optional | Only for a sheet that could cost more than the $4.99 floor. After quoting the user the up-to cap and getting approval, call again with this set to the quoted cap. Charged only for cohorts with a curve, never above the cap. Leave empty on the first (quote) call. | 39.6 |
What comes back
- Retention: the last month's median asking price at exit as a percent of the first, with n at each end, the odometer drift in miles and the units over the window
- Twelve months of the cohort, month by month: units, the priced sample, the median asking price, the median odometer and days to sell, pinned to one model year
- The whole used market rebased to the same start on one chart, with the cohort and market medians side by side
- With a powertrain: the cohort filtered to it against a combustion comparator, and which comparator was used
- Three reads from the numbers: the cohort, the market beside it, and the low point of the window
- Portfolio sheet: one row per cohort sorted lowest retention first, a totals strip and a CSV of every row
Asking for it in a chat client
Show the 12-month value-retention curve for 2022 Toyota Camrys nationally
Run a portfolio retention sheet for these 40 cohorts (paste list)
Running it from a backend
Grant an agent the reports:value-retention-curve scope, then call the tool over MCP:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "generate_value_retention_curve",
"arguments": {
"year": 2022,
"make": "Toyota",
"model": "Camry",
"inventory_type": "used",
"months": 12
}
}
}
See Server-side access for the token exchange and how to read the response.