# Search Active Cars

> Full reference for the search_active_cars tool — search live vehicle inventory across US and Canada with 80+ filter parameters, faceted search, and dealer-specific inventory retrieval.

Search for cars **currently listed for sale** in the US and Canada. This is the primary tool for live inventory search, supporting dealer, private party, and auction listings.



## Overview

| Property | Value    |
|----------|----------|
| Tool name | `search_active_cars` |
| Markets | US, Canada |
| Seller types | `dealer` (default), `fsbo` (private seller), `auction` |
| Default rows | 5 (max 50) for standard search; 1,500 for dealer/syndication search |
| API endpoints | See below |




### API Endpoint Routing

The tool automatically selects the right API endpoint based on your parameters:

| Condition | Endpoint  | Max Rows  |
|-----------|-----------|-----------|
| Default (`seller_type="dealer"`) | `GET /v2/search/car/active` | 50 |
| `seller_type="fsbo"` | `GET /v2/search/car/fsbo/active` | 50 |
| `seller_type="auction"` | `GET /v2/search/car/auction/active` | 50 |
| Any dealer identifier provided (`dealer_id`, `source`, `mc_website_id`, `mc_dealer_id`, `mc_location_id`, `mc_rooftop_id`, `mc_dealership_group_id`, `mc_dealership_group_name`, `mc_sub_dealership_group_id`, `mc_sub_dealership_group_name`, `mc_category`) | `GET /v2/dealerships/inventory` | 1,500 |


> **NOTE**: 
> The routing is automatic. When any dealer-specific identifier is provided, the tool switches to the Dealer Inventory Syndication API (`/v2/dealerships/inventory`) which is optimized for full dealer inventory retrieval — returning up to 1,500 listings per call instead of the standard 50 limit.



## Critical Workflow

Before filtering on categorical fields, always run a facets call to discover available values:

```text
# Step 1 — discover values
search_active_cars(facets="make,model,body_type,powertrain_type", rows=1, state="CA")

# Step 2 — search with validated values
search_active_cars(make="Toyota", powertrain_type="HEV,PHEV", state="CA")
```



## Parameters



### Vehicle Specifications

| Parameter   | Type        | Description |
|-------------|-------------|-------------|
| `make` | string | Manufacturer (e.g., `"Toyota"`, `"Ford"`) |
| `model` | string | Model name (e.g., `"Camry"`, `"F-150"`) |
| `year` | int | Model year (e.g., `2022`) |
| `year_range` | string | Range format `"min-max"` (e.g., `"2019-2023"`) |
| `trim` | string | Trim level — use facets to validate |
| `car_type` | string | `"new"`, `"used"`, or `"certified"` |
| `body_type` | string | Body style (e.g., `"SUV"`, `"Sedan"`) — use facets |
| `powertrain_type` | string | **Recommended over fuel_type**. Values: `"Combustion"`, `"HEV"`, `"MHEV"`, `"BEV"`, `"PHEV"`, `"FCEV"`, `"EREV"` |
| `fuel_type` | string | Non-normalized values — prefer `powertrain_type` or use facets |
| `drivetrain` | string | e.g., `"AWD"`, `"FWD"`, `"RWD"` |
| `transmission` | string | Transmission type — use facets |
| `engine` | string | Engine description |
| `cylinders` | int | Number of cylinders (4, 6, 8) |
| `doors` | int | Number of doors (2, 4) |
| `seating_capacity` | int | Number of seats (5, 7, 8) |




### Location Filters

| Parameter   | Type        | Description |
|-------------|-------------|-------------|
| `zip` | string | ZIP code |
| `city` | string | City name |
| `state` | string | 2-letter state code (e.g., `"CA"`, `"TX"`) |
| `latitude` | float | Latitude coordinate |
| `longitude` | float | Longitude coordinate |
| `radius` | int | Search radius in miles |




### Price & Mileage

| Parameter   | Type        | Description |
|-------------|-------------|-------------|
| `price_range` | string | Price range `"min-max"` (e.g., `"20000-50000"`) |
| `miles_range` | string | Mileage range `"min-max"` (e.g., `"0-30000"`) |
| `msrp_range` | string | MSRP range `"min-max"` |




### Color Filters

| Parameter   | Type        | Description |
|-------------|-------------|-------------|
| `exterior_color` | string | Exterior color, comma-separated — use facets |
| `interior_color` | string | Interior color, comma-separated |
| `base_exterior_color` | string | Normalized base exterior color |
| `base_interior_color` | string | Normalized base interior color |




### Market Timing

| Parameter   | Type        | Description |
|-------------|-------------|-------------|
| `dom_range` | string | Days on market range `"min-max"` |
| `dom_active_range` | string | Active days on market range |
| `first_seen_days` | string | First seen days `"max-min"` (e.g., `"30-10"` = 10–30 days ago) |
| `last_seen_days` | string | Last seen days `"max-min"` |




### Seller & Dealer

| Parameter   | Type        | Description |
|-------------|-------------|-------------|
| `seller_type` | string | `"dealer"` (default), `"fsbo"`, `"auction"` |
| `dealer_id` | string | Specific dealer ID |
| `dealer_type` | string | `"franchise"` or `"independent"` |
| `mc_dealership_group_name` | string | Dealership group name filter |


> **NOTE**: 
> When any dealer identifier (`dealer_id`, `mc_website_id`, `mc_dealer_id`, etc.) is provided, the tool automatically routes to the Dealer Inventory Syndication API for optimized dealer-specific retrieval with up to 1,500 results per call.



### Features & Options

| Parameter   | Type        | Description |
|-------------|-------------|-------------|
| `high_value_features` | string | Filter by high-value features (intersection). **Always discover values with facets first**: `facets="high_value_features|0|1000"` |
| `options_packages` | string | Filter by installed packages. Discover with: `facets="options_packages_mv|0|1000"` |




### Carfax Filters

| Parameter   | Type        | Description |
|-------------|-------------|-------------|
| `carfax_1_owner` | string | One-owner vehicle |
| `carfax_clean_title` | string | Clean ownership records |




### Analytics & Facets

| Parameter   | Type        | Description |
|-------------|-------------|-------------|
| `facets` | string | Discover unique values and counts. Syntax: `"field|offset|limit|min_count"` |
| `stats` | string | Generate statistics for fields (e.g., `"price,miles,dom"`) |
| `range_facets` | string | Numeric range facets |




### Sorting & Pagination

| Parameter   | Type        | Default     | Description |
|-------------|-------------|-------------|-------------|
| `sort_by` | string | — | Sort field (e.g., `price`, `miles`, `dom`, `dist`) |
| `sort_order` | string | `"asc"` | `"asc"` or `"desc"` |
| `rows` | int | 5 | Results to return (max 50) |
| `start` | int | 0 | Pagination offset |




### Response Control (MCP-only)

| Parameter   | Type        | Default     | Description |
|-------------|-------------|-------------|-------------|
| `fetch_all_photos` | bool | `false` | Return all photos vs. single photo per listing |
| `include_dealer_object` | bool | `false` | Include full dealer details |
| `include_mc_dealership_object` | bool | `false` | Include MarketCheck dealership metadata |
| `include_build_object` | bool | `false` | Include full vehicle build/specs |




## Use Cases



### Search for EVs in California under $50K

```text
search_active_cars(
  state="CA",
  powertrain_type="BEV",
  price_range="0-50000",
  rows=10
)
```



### Discover available makes for SUVs

```text
search_active_cars(
  facets="make|0|50",
  body_type="SUV",
  rows=1
)
```



### Find low-mileage certified vehicles

```text
search_active_cars(
  make="Toyota",
  model="Camry",
  car_type="certified",
  miles_range="0-25000",
  year_range="2022-2024"
)
```



### Get pricing statistics for a market segment

```text
search_active_cars(
  make="Ford",
  model="F-150",
  state="TX",
  stats="price,miles,dom",
  rows=1
)
```



### Dealer inventory lookup

```text
search_active_cars(
  dealer_id="12345",
  rows=50,
  include_dealer_object=true
)
```



## See Also

- [Search Past 90 Days](/docs/get-started/api/mcp/tools/search-past-90-days) — Historical/sold listing search
- [Workflows & Use Cases](/docs/get-started/api/mcp/workflows) — Common multi-tool patterns