--- title: "Vehicle Market Value (v2)" method: GET path: "/v2/marketvalue" tags: ["Market Value"] --- # Vehicle Market Value (v2) `GET /v2/marketvalue` ## Request - Base URL: `https://api.carsxe.com` - URL: `https://api.carsxe.com/v2/marketvalue` - Auth: one of: - API key in query parameter `key` - API key in header `PAYMENT-SIGNATURE` - none - TypeScript: (a function with typed inputs; its response is checked against the schema) Get detailed market values for a VIN, including wholesale, retail, trade-in, and auction values across condition tiers. The response includes mileage_list (odometer-band adjustments, with finadv and mileage_cat when present) and add_deduct_list (option/equipment adds and deducts). Pass mileage to apply the matching band's condition column to every mileage_* tier automatically; condition is optional and does not gate those adjustments. Otherwise apply bands yourself. Optional state selects the regional adjustment. Credit plans: 25 credits per successful billable lookup. Failed lookups and no-data errors do not use credits. See https://carsxe.com/pricing.md for billing units. ## Query parameters - `vin` string, required - `state` string - `mileage` number - `condition` 'excellent' | 'clean' | 'average' | 'rough' ## Response `200` Market value retrieved. - object: Full v2 market value payload. Passing mileage applies the matching mileage_list band's condition column to every mileage_* tier and recalculates adjusted_*. condition is optional. add_deduct_list describes option/equipment adjustments. - `uid` string: Valuation record identifier. - `input` object: Echo of request inputs: vin, state, country, and mileage and condition when provided. - `vin` string - `state` string - `country` string - `mileage` number: Present when the mileage query parameter was sent. - `condition` string: Present when the condition query parameter was sent. - `publish_date` string: Provider valuation publish date. - `data_freq` string: Refresh frequency. D means daily. - `state` string - `country` string - `uvc` string: Unique vehicle code. - `group_num` string - `model_year` string - `make` string - `model` string - `series` string - `style` string - `mileage_cat` string - `class_code` string - `class_name` string - `description_score` string - `first_values_flag` boolean - `risk_score` string - `whole_xclean` object: Condition valuation object. Nested keys are prefixed with the family and condition, for example base_retail_clean, mileage_retail_clean, add_deduct_retail_clean, regional_retail_clean, and adjusted_retail_clean. adjusted_* = base_* + mileage_* + add_deduct_* + regional_*. - `whole_clean` object: Condition valuation object. Nested keys are prefixed with the family and condition, for example base_retail_clean, mileage_retail_clean, add_deduct_retail_clean, regional_retail_clean, and adjusted_retail_clean. adjusted_* = base_* + mileage_* + add_deduct_* + regional_*. - `whole_avg` object: Condition valuation object. Nested keys are prefixed with the family and condition, for example base_retail_clean, mileage_retail_clean, add_deduct_retail_clean, regional_retail_clean, and adjusted_retail_clean. adjusted_* = base_* + mileage_* + add_deduct_* + regional_*. - `whole_rough` object: Condition valuation object. Nested keys are prefixed with the family and condition, for example base_retail_clean, mileage_retail_clean, add_deduct_retail_clean, regional_retail_clean, and adjusted_retail_clean. adjusted_* = base_* + mileage_* + add_deduct_* + regional_*. - `retail_xclean` object: Condition valuation object. Nested keys are prefixed with the family and condition, for example base_retail_clean, mileage_retail_clean, add_deduct_retail_clean, regional_retail_clean, and adjusted_retail_clean. adjusted_* = base_* + mileage_* + add_deduct_* + regional_*. - `retail_clean` object: Condition valuation object. Nested keys are prefixed with the family and condition, for example base_retail_clean, mileage_retail_clean, add_deduct_retail_clean, regional_retail_clean, and adjusted_retail_clean. adjusted_* = base_* + mileage_* + add_deduct_* + regional_*. - `retail_avg` object: Condition valuation object. Nested keys are prefixed with the family and condition, for example base_retail_clean, mileage_retail_clean, add_deduct_retail_clean, regional_retail_clean, and adjusted_retail_clean. adjusted_* = base_* + mileage_* + add_deduct_* + regional_*. - `retail_rough` object: Condition valuation object. Nested keys are prefixed with the family and condition, for example base_retail_clean, mileage_retail_clean, add_deduct_retail_clean, regional_retail_clean, and adjusted_retail_clean. adjusted_* = base_* + mileage_* + add_deduct_* + regional_*. - `trade_in_clean` object: Condition valuation object. Nested keys are prefixed with the family and condition, for example base_retail_clean, mileage_retail_clean, add_deduct_retail_clean, regional_retail_clean, and adjusted_retail_clean. adjusted_* = base_* + mileage_* + add_deduct_* + regional_*. - `trade_in_avg` object: Condition valuation object. Nested keys are prefixed with the family and condition, for example base_retail_clean, mileage_retail_clean, add_deduct_retail_clean, regional_retail_clean, and adjusted_retail_clean. adjusted_* = base_* + mileage_* + add_deduct_* + regional_*. - `trade_in_rough` object: Condition valuation object. Nested keys are prefixed with the family and condition, for example base_retail_clean, mileage_retail_clean, add_deduct_retail_clean, regional_retail_clean, and adjusted_retail_clean. adjusted_* = base_* + mileage_* + add_deduct_* + regional_*. - `region2` number: Raw regional adjustment for region 2. - `region3` number: Raw regional adjustment for region 3. - `region4` number: Raw regional adjustment for region 4. - `region5` number: Raw regional adjustment for region 5. - `region6` number: Raw regional adjustment for region 6. - `msrp` number - `retail_equipped` number - `price_includes` string - `wheel_base` number - `tire_size` string - `gvw` number - `payload_cap` number - `seat_cap` string - `seats` string - `fuel_type` string - `fuel_cap` string - `fuel_delivery` string - `hwy_mpg` string - `city_mpg` string - `engine_description` string - `cylinders` string - `engine_displacement` string - `engine_turbocharged` string - `base_hp` string - `taxable_hp` number - `torque` string - `oil_cap` string - `transmission` string - `drivetrain` string - `num_gears` string - `ext_doors` string - `navigation` string - `airbags` string: Airbag configuration. - `anti_corrosion_warranty` string: Corrosion / rust warranty. - `basic_warranty` string - `road_assist_warranty` string: Roadside-assistance warranty. - `add_deduct_list` object[]: Option and equipment adds and deducts. These adjust market value based on options the vehicle may have. - `uoc` string: Unique option code. - `name` string: Option or equipment name. - `xclean` number - `clean` number - `avg` number - `rough` number - `auto` string: Whether the option is treated as automatic / default (Y or N). - `resid12` number - `resid24` number - `resid30` number - `resid36` number - `resid42` number - `resid48` number - `resid60` number - `resid72` number - `model_number_list` string[] - `mileage_list` object[]: Odometer-band table. If mileage is passed, the API applies the matching band's condition column to every mileage_* tier automatically. condition is not required. - `model_year` string: Model year this band applies to. - `range_begin` number: Inclusive start of the odometer band. - `range_end` number: Inclusive end of the odometer band. - `xclean` number: Adjustment for extra-clean / excellent condition. - `clean` number: Adjustment for clean condition. - `avg` number: Adjustment for average condition. - `rough` number: Adjustment for rough condition. - `finadv` number: Finance-advance adjustment for this band, when supplied. - `mileage_cat` string: Mileage category for the band. Matches top-level mileage_cat. - `retail` number: Typical retail asking value (base_retail_avg). - `trade_in` number: Typical clean trade-in value (base_trade_in_clean). - `rough_trade_in` number: Rough-condition trade-in value. - `average_trade_in` number: Average-condition trade-in value. - `loan_value` number: Typical loan / finance value (base_retail_clean). - `trade_in_values` unknown[]: Historical trade-in series when supplied. Often empty on v2. - unknown - `auction_values` object - `low_auction_value` number - `average_auction_value` number - `high_auction_value` number - `date_range` string ## Other responses - `400`: Missing/invalid VIN, mileage or condition. - `401`: Missing API key, unknown/disabled API key, or inactive account. - `404`: No data found for this VIN. - `429`: API usage limit exceeded for the current billing period. - `500`: Internal server error. - `503`: Upstream market value provider is unavailable. ## Changes - **2026-11-07** `ed8f6c024239`: 2 info - added the optional property `input/condition` to the response with the `200` status - added the optional property `input/mileage` to the response with the `200` status - **2026-09-23** `e0ce48cea6a6`: 60 info - added the optional property `add_deduct_list` to the response with the `200` status - added the optional property `airbags` to the response with the `200` status - added the optional property `anti_corrosion_warranty` to the response with the `200` status - added the optional property `auction_values` to the response with the `200` status - …56 more [Operation history](https://skmtc.dev/carsxe/apis/carsxe-api/changes/v2/marketvalue/get.md) --- [API](https://skmtc.dev/carsxe/apis/carsxe-api.md) - [All operations](https://skmtc.dev/carsxe/apis/carsxe-api/llms.txt) - [OpenAPI document](https://skmtc.dev/carsxe/apis/carsxe-api/revisions/ed8f6c024239?raw)