# Sold Summary

> Comprehensive sold vehicle analytics with advanced filtering, ranking, and grouping — covering up to 5 years of historical US sales data via the MarketCheck MCP Server.

> **WARNING**: 
> **Experimental · Enterprise Only** — This tool is currently in experimental status and available exclusively to Enterprise API subscribers. Features and parameters may change. Contact your account manager for access.

Get comprehensive **sold vehicle analytics** with advanced filtering, ranking, and grouping — covering up to **5 years of historical sales data** in the US market.



## Overview

| Property | Value    |
|----------|----------|
| Market | US only |
| Data depth | Up to 5 years of sold vehicle data |
| API endpoint | `GET /api/v1/sold-vehicles/summary` |
| Default limit | 1000 results |
| Pricing model | Variable per-query (see [Pricing](#pricing) below) |




## Pricing

Unlike the standard MarketCheck API tools — which are included in your subscription and billed at a flat per-request rate — the Sold Summary tool operates on a **variable per-query pricing** model.



### Why Variable Pricing?

Each Sold Summary query runs against a large-scale analytical data warehouse containing billions of historical transaction records. The compute cost of a query depends on its complexity: how many dimensions you group by, the date range you scan, the filters you apply, and the volume of data that matches. A simple single-state, single-make query over one quarter costs significantly less than a nationwide, multi-dimensional analysis spanning five years.



### How It Works

| Aspect | Detail |
|--------|--------|
| **Billing basis** | Per query, based on actual compute resources consumed |
| **Cost drivers** | Date range span, number of ranking dimensions, result volume, filter specificity |
| **Billing method** | Charged to your account's payment method on file (Stripe) |
| **Visibility** | Each query response includes the estimated cost in the response metadata |




### Cost Optimization Tips

- **Narrow your date range** — Querying one quarter costs less than querying five years
- **Use specific filters** — Adding `state`, `make`, or `inventory_type` reduces the data scanned
- **Limit dimensions** — Fewer `ranking_dimensions` means less aggregation compute
- **Use top_n** — Capping results reduces post-processing overhead

> **IMPORTANT**: 
> **Coming Soon** — Per-query billing via Stripe is currently being integrated. During the preview period, usage is tracked but billing is not yet active. Contact your account manager for current pricing details and to set up your billing account.



## Parameters



### Time Period

| Parameter   | Type        | Default     | Description |
|-------------|-------------|-------------|-------------|
| `date_from` | date | — | Start date (`YYYY-MM-DD`, first day of month) |
| `date_to` | date | — | End date (`YYYY-MM-DD`, last day of month) |




### Basic Filters

| Parameter    | Type         | Valid Values | Description  |
|--------------|--------------|--------------|--------------|
| `inventory_type` | string | `"New"`, `"Used"` | Filter by inventory type |
| `dealer_type` | string | `"Franchise"`, `"Independent"` | Filter by dealer type |
| `state` | string | 2-letter state code (e.g., `"CA"`, `"TX"`) | Filter by US state |




### Vehicle Filters

| Parameter   | Type        | Description |
|-------------|-------------|-------------|
| `make` | string | Manufacturer (e.g., `"Toyota"`, `"Ford"`) |
| `model` | string | Model name (e.g., `"Camry"`, `"F-150"`) |
| `body_type` | string | Body style (e.g., `"SUV"`, `"Sedan"`, `"Pickup"`, `"Hatchback"`) |
| `fuel_type_category` | string | `"ICE"`, `"EV"`, `"Hybrid"`, `"Unknown"`, `"Other"` |




### Dealership Filter

| Parameter   | Type        | Description |
|-------------|-------------|-------------|
| `dealership_group_name` | string | Exact dealership group name (e.g., `"AutoNation Inc."`, `"Hendrick Automotive Group"`, `"Lithia Motors Inc."`). 481 groups supported; if an invalid name is provided, the tool returns the complete list of valid options. |




### Ranking & Grouping

| Parameter   | Type        | Default     | Description |
|-------------|-------------|-------------|-------------|
| `ranking_dimensions` | string | `"make,model,body_type"` | Comma-separated dimensions to group by. Valid values: `make`, `model`, `body_type`, `dealership_group_name` |
| `ranking_measure` | string | `"sold_count"` | Metric to rank by: `"sold_count"`, `"average_sale_price"`, `"total_sale_price"`, `"average_days_on_market"`, `"price_over_msrp_percentage"` |
| `ranking_order` | string | `"desc"` | Sort order: `"asc"` or `"desc"` |
| `top_n` | int | — | Limit results per group (must be ≥ 1) |
| `summary_by` | string | `"state"` | Geographic grouping: `"state"` or `"city_state"` |




### Pagination

| Parameter   | Type        | Default     | Description |
|-------------|-------------|-------------|-------------|
| `limit` | int | `1000` | Max results (1–5000) |




### Advanced Numeric Filters

Use comparison operators (`>`, `<`, `>=`, `<=`, `=`) followed by a number.

| Parameter      | Type           | Example Values | Description    |
|----------------|----------------|----------------|----------------|
| `sold_count` | string | `">100"`, `"<=50"` | Filter by number of vehicles sold |
| `average_sale_price` | string | `">20000"`, `"<=15000.50"` | Filter by average sale price |
| `total_sale_price` | string | `">500000"` | Filter by total sales volume |
| `average_days_on_market` | string | `">30"`, `"<=60"` | Filter by average days to sell |
| `price_over_msrp_percentage` | string | `">5"`, `"<=0"` | Filter by % premium/discount vs MSRP |




## Returns

JSON string with summary records, each containing:

| Field       | Description |
|-------------|-------------|
| `sold_count` | Number of vehicles sold |
| `average_sale_price` | Average transaction price |
| `total_sale_price` | Total sales volume |
| `price_range` | Min/max sale prices |
| `std_deviation` | Price standard deviation |
| `price_over_msrp_percentage` | Average premium/discount vs MSRP |
| `average_msrp` | Average MSRP |
| `average_days_on_market` | Average time to sell |
| `median_days_on_market` | Median time to sell |
| Dimension values | make, model, body_type, etc. |
| Geographic breakdown | State or city/state |




## Use Cases



### Top 10 best-selling models in California (2024)

```text
get_sold_summary(
  date_from="2024-01-01",
  date_to="2024-12-31",
  state="CA",
  ranking_dimensions="make,model",
  ranking_measure="sold_count",
  ranking_order="desc",
  top_n=10
)
```



### EV sales analysis by state

```text
get_sold_summary(
  date_from="2024-01-01",
  date_to="2024-12-31",
  fuel_type_category="EV",
  inventory_type="New",
  ranking_dimensions="make,model",
  ranking_measure="sold_count"
)
```



### Vehicles selling above MSRP

```text
get_sold_summary(
  inventory_type="New",
  price_over_msrp_percentage=">0",
  ranking_dimensions="make,model,body_type",
  ranking_measure="price_over_msrp_percentage",
  ranking_order="desc"
)
```



### Fastest-selling SUVs by dealership group

```text
get_sold_summary(
  body_type="SUV",
  ranking_dimensions="dealership_group_name",
  ranking_measure="average_days_on_market",
  ranking_order="asc",
  top_n=20
)
```



### Dealership group performance comparison

```text
get_sold_summary(
  dealership_group_name="AutoNation Inc.",
  date_from="2024-01-01",
  date_to="2024-12-31",
  ranking_dimensions="make,model",
  ranking_measure="sold_count",
  summary_by="city_state"
)
```



### High-volume luxury segment analysis

```text
get_sold_summary(
  make="BMW",
  inventory_type="New",
  sold_count=">50",
  average_sale_price=">50000",
  ranking_dimensions="model,body_type",
  ranking_measure="average_sale_price"
)
```



### Hybrid market trends

```text
get_sold_summary(
  fuel_type_category="Hybrid",
  date_from="2023-01-01",
  date_to="2024-12-31",
  ranking_dimensions="make,model",
  ranking_measure="sold_count",
  ranking_order="desc"
)
```



## See Also

- [Search Past 90 Days](/docs/get-started/api/mcp/tools/search-past-90-days) — Recent expired/sold listings (last 90 days)
- [Workflows & Use Cases](/docs/get-started/api/mcp/workflows) — Multi-tool analysis patterns