# Market prices

Market-wide statistics over active dealer-site listings. Results covering fewer than 3 dealers
are suppressed (`suppressed: too_few_dealers`). Legacy Team Velocity prices, known to be wrong on
most such sites, are excluded unless `include_suspect=true`.

## Endpoint

```
GET https://api.motorsdynamic.com/api/v2/market/prices
```

## Plan and price

| Plan | Access | Price |
| --- | --- | --- |
| Free | No | not included |
| Growth | Yes | $0.005 per call |
| Scale | Yes | $0.003 per call |
| Enterprise | Yes | contract |

A call is billed when it answers 2xx. See [pricing](https://developers.motorsdynamic.com/pricing.md).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `make` | query | string | yes |  |
| `model` | query | string | yes |  |
| `year` | query | integer | no |  |
| `year_min` | query | integer | no |  |
| `year_max` | query | integer | no |  |
| `trim` | query | string | no |  |
| `condition` | query | `new` or `used` or `cpo` | no |  |
| `include_suspect` | query | `true` or `false` | no |  |

## Example request

curl:

```bash
curl "https://api.motorsdynamic.com/api/v2/market/prices?make=Honda&model=Accord&year=2024" \
  -H "x-api-key: $MD_API_KEY"
```

JavaScript:

```javascript
const res = await fetch("https://api.motorsdynamic.com/api/v2/market/prices?make=Honda&model=Accord&year=2024", {
  headers: { "x-api-key": process.env.MD_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${(await res.json()).error}`);
const data = await res.json();
console.log(data);
```

Python:

```python
import os, requests

res = requests.get(
    "https://api.motorsdynamic.com/api/v2/market/prices?make=Honda&model=Accord&year=2024",
    headers={"x-api-key": os.environ["MD_API_KEY"]},
    timeout=10,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "data": {
    "query": {
      "make": "Honda",
      "model": "Accord",
      "year_min": 2024,
      "year_max": 2024,
      "trim": null,
      "condition": null,
      "include_suspect": false
    },
    "listings": 3,
    "dealers": 3,
    "suppressed": null,
    "price": {
      "min": 29000,
      "p10": 29400,
      "p25": 30000,
      "median": 31000,
      "p75": 32000,
      "p90": 32600,
      "max": 33000,
      "mean": 31000
    },
    "msrp_median": 32000,
    "mileage_median": 10,
    "excluded_suspect_listings": 1,
    "freshness": {
      "oldest_last_seen_at": "2026-09-24T10:00:00.000000Z",
      "newest_last_seen_at": "2026-09-24T10:00:00.000000Z",
      "as_of": "2026-09-24T10:05:00.000Z"
    },
    "provenance": {
      "v2": 1,
      "md_legacy": 2
    }
  },
  "meta": {
    "min_dealers": 3
  }
}
```

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.query` | object |  |
| `data.listings` | integer |  |
| `data.dealers` | integer |  |
| `data.suppressed` | `too_few_dealers` or `null` |  |
| `data.price` | object or null |  |
| `data.price.min` | number or null |  |
| `data.price.p10` | number or null |  |
| `data.price.p25` | number or null |  |
| `data.price.median` | number or null |  |
| `data.price.p75` | number or null |  |
| `data.price.p90` | number or null |  |
| `data.price.max` | number or null |  |
| `data.price.mean` | number or null |  |
| `data.msrp_median` | number or null |  |
| `data.mileage_median` | number or null |  |
| `data.excluded_suspect_listings` | integer |  |
| `data.freshness` | object |  |
| `data.freshness.oldest_last_seen_at` | string or null | RFC 3339 UTC with microseconds. |
| `data.freshness.newest_last_seen_at` | string or null | RFC 3339 UTC with microseconds. |
| `data.freshness.as_of` | string |  |
| `data.provenance` | object |  |
| `data.provenance.v2` | integer | Listings written by the v2 crawler. |
| `data.provenance.md_legacy` | integer | Listings written by the legacy pipeline. |
| `meta` | object |  |

## Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_parameter` | A parameter is missing or malformed. The message names it. |
| 401 | `invalid_api_key` | The key is missing, revoked or mistyped. |
| 402 | `plan_required` | The endpoint is on a higher plan. The body names the plan and links to the upgrade. |
| 403 | `not_entitled` | The key may not read this dealer or source. |
| 429 | `rate_limited or quota_exceeded` | Slow down (see `Retry-After`), or the Free monthly calls are used up. |
| 504 | `query_timeout` | The query passed its 4 second budget. Narrow the filters. Not billed. |

Every error has the same body: `{ "error": "<code>", "message": "..." }`. Full list: [errors](https://developers.motorsdynamic.com/docs/errors.md).