# Dealers

## Endpoint

```
GET https://api.motorsdynamic.com/api/v2/dealers
```

## Plan and price

| Plan | Access | Price |
| --- | --- | --- |
| Free | No | not included |
| Growth | No | not included |
| Scale | No | not included |
| 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 |
| --- | --- | --- | --- | --- |
| `host` | query | string | no | Exact host, for example `exampledealer.com` (scheme and `www.` are ignored). |
| `limit` | query | integer | no |  |
| `cursor` | query | string | no | `page.next_cursor` from the previous page, unchanged. |

## Example request

curl:

```bash
curl "https://api.motorsdynamic.com/api/v2/dealers?host=alphahonda.com&limit=50" \
  -H "x-api-key: $MD_API_KEY"
```

JavaScript:

```javascript
const res = await fetch("https://api.motorsdynamic.com/api/v2/dealers?host=alphahonda.com&limit=50", {
  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/dealers?host=alphahonda.com&limit=50",
    headers={"x-api-key": os.environ["MD_API_KEY"]},
    timeout=10,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "data": [
    {
      "id": 101,
      "url": "https://www.alphahonda.com",
      "host": "alphahonda.com",
      "name": "Alpha Honda",
      "city": "Pittsburgh",
      "state": "PA",
      "platform": "dealer-inspire",
      "tier": "serving_legacy",
      "crawl": null,
      "freshness": {
        "last_seen_at": "2026-09-24T06:00:00.000000Z"
      },
      "provenance": {
        "source": "domains"
      }
    }
  ],
  "page": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  },
  "meta": {}
}
```

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| `data[]` | array of object |  |
| `data[].id` | integer |  |
| `data[].url` | string |  |
| `data[].host` | string |  |
| `data[].name` | string or null |  |
| `data[].city` | string or null |  |
| `data[].state` | string or null |  |
| `data[].platform` | string or null |  |
| `data[].tier` | `serving_legacy` or `serving_v2` or `discovery` |  |
| `data[].crawl` | object or null |  |
| `data[].crawl.owner` | `legacy` or `v2` |  |
| `data[].crawl.serving` | boolean |  |
| `data[].crawl.next_crawl_at` | string or null | RFC 3339 UTC with microseconds. |
| `data[].crawl.last_complete_at` | string or null | RFC 3339 UTC with microseconds. |
| `data[].freshness` | object |  |
| `data[].freshness.last_seen_at` | string or null | RFC 3339 UTC with microseconds. |
| `data[].provenance` | object |  |
| `data[].provenance.source` | `domains` or `v2_domains` |  |
| `page` | object |  |
| `page.limit` | integer |  |
| `page.has_more` | boolean |  |
| `page.next_cursor` | string or null |  |
| `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).