One GET returns one number: what a given year/make/model is currently being asked for on the US dealer market, in whole USD. It is a gradient-boosted model trained on our own scraped listings store, and it publishes its own accuracy metric — median absolute percentage error on holdout data — inside every response. It is built for teams that need a programmatic price for a car they can describe but have never physically seen: trade-in widgets, marketplace price guidance, and collateral revaluation.
A flat object, not a nested valuation document. estimateUsd is the predicted market asking price as a whole integer, currency is always "USD" today, and medianApePct is the loaded model's holdout error. The field that matters most in production is inputs: an echo of the non-null feature vector the model actually scored, including derived features you never sent — age, computed as max(currentYear − year, 0), and miles_per_year, which can be fractional. For a 2021 Toyota Camry SE with 45,000 miles in TX the documented response is estimateUsd 26096 with an inputs echo showing year, age, make, model, trim, miles, miles_per_year, condition, seller_type and state. There is no per-vehicle confidence score and no prediction interval; medianApePct is model-wide. source is the constant string "carscrape", the backing data service.
The estimate comes from a gradient-boosted asking-price model trained on our scraped US dealer-listings store: 1,721,693 listings, 4,686,766 price observations and 1,719,030 distinct vehicles. Your query parameters become the model's feature vector directly — make, model, year, miles, trim, state, condition, drivetrain, fuel, transmission, body_style, color and base_msrp — plus two derived features the API computes for you, vehicle age and miles per year. The API forwards the request to the valuation service with a 5-second budget and returns a rounded integer. If no trained pricing model is currently loaded, you get a retryable 503 valuation_model_unavailable rather than a stale or fabricated number. medianApePct is measured on holdout data, meaning half of held-out predictions land within 3.7% of the observed listing price; it is reported per response so you can see when a redeployed model changes accuracy, not as a per-vehicle confidence.
Data source
A gradient-boosted asking-price model trained on our scraped US dealer-listings store. The estimate is a market ASKING price from live dealer listings, not a realized transaction price.
Route budget
5 s
Billed per
model estimate, successful responses only
MCP tool
get_market_value
Limits: what this endpoint will not do
This is an asking price from live US dealer listings, not a realized transaction price and not private-party. If you need a wholesale, trade-in or auction number, this is an input to your own model, not a drop-in replacement. There is no 404 path: the model always returns a number, even for a make/model combination it has never seen — so the inputs echo is not a debugging nicety, it is how you confirm which parameters were actually recognized. Casing is load-bearing because model is not canonicalized. Verified on live data for a 2021 Camry SE at 45,000 miles: model=Camry with state=TX returns $26,096; model=camry returns $23,882; state=tx returns $21,248, identical to omitting state entirely. Send Title-Case model names and uppercase state codes. Omitting miles materially lowers accuracy because it also removes the derived miles-per-year feature. Coverage is US-market and USD-only, and there is no VIN parameter — decode the VIN first and pass its normalized attributes. Market Value shares the free Starter plan's 1,000 monthly calls. After that shared allowance, estimates cost $0.015 from the one-time $10 signup credit — enough for roughly 666 additional estimates — and return 402 insufficient_credits only when both are exhausted, never a surprise invoice. The endpoint is available now and successful responses use the published catalog rate. Standard plans include no SLA.
What teams build with it
Instant trade-in and what-is-my-car-worth widgets
A franchise dealer group or an acquisition/lead-gen site collects year, make, model, trim, mileage and state from a seller form and calls market value on submit. Because the model returns an asking price rather than a wholesale bid, most operators present a range derived from medianApePct and apply their own acquisition margin before showing an offer. Chain the depreciation endpoint on the same make/model to show the seller what waiting six months costs them — that pairing is why the two endpoints share a price.
Seller-side price guidance on a used-car marketplace
A peer-to-peer or dealer marketplace shows comparable cars are asking about $X at listing-creation time to reduce mispriced inventory. The honest version of this feature calls market value for the number and the listings search endpoint for the comparable set behind it, so the seller sees the actual live inventory the estimate is consistent with rather than an unexplained figure.
Monthly collateral revaluation for auto lenders
A credit union, buy-here-pay-here lender or auto-loan fintech re-prices a book of collateral by batching one call per loan with the stored year/make/model/trim/mileage/state, then comparing estimateUsd against outstanding principal to flag underwater positions. Two caveats you must build in: this is an asking price, so apply your own asking-to-wholesale haircut, and the endpoint has no VIN parameter, so store decoded attributes rather than raw VINs at write time.
Stated-value prefill in insurance quoting
An insurtech prefilling a vehicle's stated value at quote time can drop the manual entry step and reduce quote abandonment. Send state as an uppercase two-letter code — geography is a real feature, and a lowercase value is silently treated as an unseen category, which is worth roughly $4,800 on the documented Camry example.
Integrating it properly
The reference ships the bare curl. This is the shape worth deploying: a typed client that branches on the RFC 9457 code slug rather than the human-readable title, and retries only the codes this endpoint marks retryable.
TypeScript
const API = "https://api.vehicles.dev";
// Only these codes are marked retryable for this endpoint. Everything else is terminal.
const RETRYABLE = new Set(["valuation_model_unavailable", "valuation_upstream_unavailable"]);
export async function getMarketValue(params: Record<string, string>, attempt = 0): Promise<GetMarketValueResponse> {
const response = await fetch(
`${API}/v1/vehicles/market-value?${new URLSearchParams(params).toString()}`,
{
headers: {
Accept: "application/json",
Authorization: `Bearer ${process.env.VEHICLES_API_KEY ?? ""}`
},
// The route budget is 5 s; allow it plus headroom.
signal: AbortSignal.timeout(10_000)
}
);
if (response.ok) return (await response.json()) as GetMarketValueResponse;
// Failures are application/problem+json. Branch on `code`, never on the human-readable title.
const problem = (await response.json()) as { code: string; detail?: string };
if (RETRYABLE.has(problem.code) && attempt < 3) {
await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
return getMarketValue(params, attempt + 1);
}
throw new Error(`${response.status} ${problem.code}: ${problem.detail ?? ""}`);
}
How to check it is behaving
The route enforces a 5-second upstream budget, so a slow dependency returns a problem document instead of holding your request open. Exactly 2 codes are marked retryable here — valuation_model_unavailable and valuation_upstream_unavailable — and everything else documented for this endpoint is terminal, so backoff on anything else just burns your rate limit. Billing is success-only: failed calls release their reservation, so you can measure error rates and hold-out accuracy against your own data without paying for the failures. Usage is visible per endpoint in the dashboard.
What this one endpoint costs
Priced per model estimate. The platform fee buys throughput and endpoint access; the unit price covers the data work. Worked at 50,000 successful calls a month so you can see where the plans cross over — the full price matrix is in the reference.
Vehicle Valuation API pricing by plan
Plan
Platform fee
Rate limit
Per model estimate
50,000 / month
Starter
$0 / mo
5 rps
$0.015
$750$750 usage + platform fee
Pro
$299 / mo
10 rps
$0.015
$1,049$750 usage + platform fee
Scale
$599 / mo
50 rps
$0.01
$1,099$500 usage + platform fee
Eligible for the Starter plan's included monthly calls; past those it draws on your credit balance. Data fees are prepaid from credits on every plan: when included calls and credits cannot cover a call you get 402 insufficient_credits rather than an overage bill. Published rates are active and apply only to successful responses. Standard plans include no SLA.
Questions engineers actually ask
Is this a retail price, a trade-in value or a transaction price?
It is a predicted market asking price from live US dealer listings. It is not a realized transaction price, not a wholesale or auction number, and not a trade-in offer. Lenders and acquisition teams typically apply their own haircut to move from asking price to the number they will actually pay or book.
Why did a make/model I made up still return a price?
There is no 404 path on this endpoint. Unrecognized categorical values are scored as unseen categories rather than rejected, so the model still produces a number. Always read the inputs object in the response: it echoes only the non-null features that were actually scored, which is the fastest way to catch a typo or a casing mistake before it reaches your users.
Does casing really change the estimate?
Yes, on model and state. make is canonicalized upstream so it is forgiving, but model is matched against the store's canonical casing ("Camry", "F-150", "4Runner") and state must be uppercase. The documented 2021 Camry SE swings from $26,096 to $23,882 to $21,248 on casing alone. Normalize before you call.
What does medianApePct actually tell me?
That the loaded model's median absolute percentage error on holdout data is 3.7% — half of held-out predictions land within 3.7% of the observed listing price. It is a model-wide metric, identical on every response, so it is not a confidence score for your specific vehicle. There is no per-vehicle prediction interval today.
Can I value a car straight from a VIN?
Not with this endpoint — it takes attributes, not a VIN. Decode the VIN first with the VIN Decoder API, then pass the resulting year, make, model, and trim along with mileage and state when you have them.
What does it cost, and when should I be on Scale?
Starter's first 1,000 calls are shared across all eleven synchronous vehicle data APIs; after that, Market Value is $0.015 per successful estimate from available credit. Pro is $0.015 and Scale is $0.01. Worked example: 50,000 estimates a month is $750 in data fees plus $299 on Pro ($1,049) versus $500 plus $599 on Scale ($1,099) — the crossover is around 60,000 calls a month. Only successful responses bill; validation errors, rate-limit rejections and upstream failures cost nothing.
Where to go next
Most integrations chain two or three of these. The ones that pair with vehicle valuation api most often:
Car Depreciation APIMSRP retention by model year, a smoothed age 0–12 retention curve and one fitted annual decay rate, for 223 covered make/model pairs.
Cost of Ownership APIEPA annual and five-year fuel cost, combined MPG and tailpipe CO2 for a year/make/model. Fuel only — pair it with depreciation for a real ownership total.
Car Listings APIFilter 1,721,693 normalized US dealer listings by make, model, year, price, mileage and state, and get the total match count alongside the page.