Get Stats

Return price range, median, average, sell-through, and 12-month trend stats for a normalized vehicle make and optional model. This endpoint requires a paid API plan.

GET https://api.oldcarsdata.com/stats

Paid plan required

GET /stats is not available on the Starter plan. Use it when your integration needs aggregate market context instead of individual auction rows.

Use normalized names

Pass the exact make string from GET /makes. When filtering by model, pass the matching model string from GET /models. On MCP, use list_makes and list_models before calling get_price_stats.

Authentication

This endpoint requires authentication. Include your API key in the Authorization header:

text

Authorization: Bearer YOUR_API_KEY

Rules

make is required. Use the exact normalized make from GET /makes.
model is optional. If omitted, stats are calculated across the full make. Use the exact normalized model from GET /models.
year_min and year_max are inclusive. Use either one independently or combine them for a bounded production window.
Price fields use sold auctions with positive prices. Excluded auction statuses are removed before the stats are calculated.
sell_through_rate is rounded to two decimal places. It is calculated as sold auctions divided by all matching auctions after excluded statuses are removed.
price_trend is a 12-month series. Each row is one month of matching sold-auction volume and average sold price.

Filter Modes

Mode	Example	Behavior
Make-level stats	`/stats?make=Porsche`	Summarizes all normalized Porsche models together.
Model-level stats	`/stats?make=Porsche&model=911`	Summarizes one normalized model.
Year-window stats	`/stats?make=Toyota&model=Land+Cruiser&year_min=1980&year_max=1990`	Summarizes one make/model inside the inclusive year range.

Request Parameters

Field	Type	Required	Description
`Authorization`	header	Yes	Bearer token with your API key: `Bearer YOUR_API_KEY`
`make`	string	Yes	Exact normalized make from GET /makes.
`model`	string	No	Exact normalized model from GET /models. When omitted, stats are calculated across the full make.
`year_min`	integer	No	Minimum vehicle year, inclusive. Combine with `year_max` to focus on a generation or production window.
`year_max`	integer	No	Maximum vehicle year, inclusive. Combine with `year_min` for a bounded year range.

Code Examples

Make and year range (cURL)

bash

curl "https://api.oldcarsdata.com/stats?make=Toyota&year_min=1980&year_max=1990" \  -H "Authorization: Bearer YOUR_API_KEY"

Make and model (cURL)

bash

curl "https://api.oldcarsdata.com/stats?make=Porsche&model=911" \  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

javascript

const params = new URLSearchParams({  make: 'Porsche',  model: '911',  year_min: '1984',  year_max: '1989',});const response = await fetch(  `https://api.oldcarsdata.com/stats?${params}`,  {    headers: {      'Authorization': 'Bearer YOUR_API_KEY'    }  });const data = await response.json();

Python

python

import requestsresponse = requests.get(    'https://api.oldcarsdata.com/stats',    params={        'make': 'Toyota',        'model': 'Land Cruiser',        'year_min': 1980,        'year_max': 1990,    },    headers={'Authorization': 'Bearer YOUR_API_KEY'})data = response.json()

MCP Equivalent

On MCP, call get_price_stats after using list_makes and list_models to confirm the normalized make and model strings.

json

{  "tool": "get_price_stats",  "arguments": {    "make": "Porsche",    "model": "911",    "year_min": 1984,    "year_max": 1989  }}

Success Response (200)

Stats retrieved successfully.

json

{  "currency": "USD",  "total_sales": 150,  "average_price": 42500,  "median_price": 40000,  "lowest_price": 15000,  "highest_price": 125000,  "sell_through_rate": 0.75,  "price_trend": [    {      "date": "2024-01",      "avg_price": 41000,      "volume": 12    },    {      "date": "2024-02",      "avg_price": 43000,      "volume": 15    }  ]}

Response Fields

Field	Type	Description
`currency`	string	ISO 4217 currency code for returned price values.
`total_sales`	number	Count of sold auctions matching the make, optional model, and year filters.
`average_price`	number	Average sold price, rounded to the nearest whole number.
`median_price`	number	Median sold price, rounded to the nearest whole number.
`lowest_price`	number	Lowest sold price in the matching result set.
`highest_price`	number	Highest sold price in the matching result set.
`sell_through_rate`	number	Sold auctions divided by all matching auctions after excluded statuses are removed, rounded to two decimal places.
`price_trend`	array	Monthly trend rows for matching sold auctions from the last 12 months.
`price_trend[].date`	string	Month in `YYYY-MM` format.
`price_trend[].avg_price`	number	Average sold price for that month, rounded.
`price_trend[].volume`	number	Number of sold auctions in that month.

Error Responses

Field	Type	Description
`error`	string	Error type identifier, such as `Forbidden`, `Unauthorized`, or `Validation Error`.
`message`	string	Human-readable error message.
`details`	object	Validation error details on 400 responses.

403 — Starter plan

json

{  "error": "Forbidden",  "message": "The stats endpoint is not available on the free plan. Please upgrade to access this feature."}

401 — Unauthorized

json

{  "error": "Unauthorized",  "message": "API key is required. Provide it via Authorization: Bearer <key> header"}

400 — Validation error

json

{  "error": "Validation Error",  "message": "make: Required",  "details": {    "make": ["Required"]  }}

Related Endpoints

GET /makes — Discover normalized make strings before querying stats.
GET /models — Discover normalized model strings for a selected make.
MCP Server — Use get_price_stats from AI tools and agents.