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.

GEThttps://api.oldcarsdata.com/stats

GET/stats?make=Porsche&model=911

Edit request2 parameters

makemodelAPI keyKept in memory for this page only and sent directly to the API.

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

Sends directly from your browser

Response example200

{
  "data": {
    "count": 4281,
    "median_price": 78400,
    "average_price": 103250,
    "min_price": 12000,
    "max_price": 1850000
  }
}

Your key is never saved to local storage or sent through the docs server.

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 covers 12 calendar months. It includes the current calendar month and the preceding 11 months. Each row is one month of matching sold-auction volume and average sold price; future-dated auctions are excluded.

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 in the current calendar month and preceding 11 months. Future-dated auctions are excluded.
`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#

400Invalid requestCheck required values and accepted formats.

401UnauthorizedAdd a valid Bearer API key.

403Access deniedVerify your email and confirm plan access.

429Rate limit reachedWait for the reset window before retrying.

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"]  }}

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.

Get Stats#

Authentication#

Rules#

Filter Modes#

Request Parameters#

Code Examples#

Make and year range (cURL)#

Make and model (cURL)#

JavaScript#

Python#

MCP Equivalent#

Success Response (200)#

Response Fields#

Error Responses#

Related Endpoints#