MarketCheck Home

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

PropertyValue
Tool namesearch_active_cars
MarketsUS, Canada
Seller typesdealer (default), fsbo (private seller), auction
Default rows5 (max 50) for standard search; 1,500 for dealer/syndication search
API endpointsSee below

API Endpoint Routing

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

ConditionEndpointMax Rows
Default (seller_type="dealer")GET /v2/search/car/active50
seller_type="fsbo"GET /v2/search/car/fsbo/active50
seller_type="auction"GET /v2/search/car/auction/active50
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/inventory1,500
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:

# 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

ParameterTypeDescription
makestringManufacturer (e.g., "Toyota", "Ford")
modelstringModel name (e.g., "Camry", "F-150")
yearintModel year (e.g., 2022)
year_rangestringRange format "min-max" (e.g., "2019-2023")
trimstringTrim level — use facets to validate
car_typestring"new", "used", or "certified"
body_typestringBody style (e.g., "SUV", "Sedan") — use facets
powertrain_typestringRecommended over fuel_type. Values: "Combustion", "HEV", "MHEV", "BEV", "PHEV", "FCEV", "EREV"
fuel_typestringNon-normalized values — prefer powertrain_type or use facets
drivetrainstringe.g., "AWD", "FWD", "RWD"
transmissionstringTransmission type — use facets
enginestringEngine description
cylindersintNumber of cylinders (4, 6, 8)
doorsintNumber of doors (2, 4)
seating_capacityintNumber of seats (5, 7, 8)

Location Filters

ParameterTypeDescription
zipstringZIP code
citystringCity name
statestring2-letter state code (e.g., "CA", "TX")
latitudefloatLatitude coordinate
longitudefloatLongitude coordinate
radiusintSearch radius in miles

Price & Mileage

ParameterTypeDescription
price_rangestringPrice range "min-max" (e.g., "20000-50000")
miles_rangestringMileage range "min-max" (e.g., "0-30000")
msrp_rangestringMSRP range "min-max"

Color Filters

ParameterTypeDescription
exterior_colorstringExterior color, comma-separated — use facets
interior_colorstringInterior color, comma-separated
base_exterior_colorstringNormalized base exterior color
base_interior_colorstringNormalized base interior color

Market Timing

ParameterTypeDescription
dom_rangestringDays on market range "min-max"
dom_active_rangestringActive days on market range
first_seen_daysstringFirst seen days "max-min" (e.g., "30-10" = 10–30 days ago)
last_seen_daysstringLast seen days "max-min"

Seller & Dealer

ParameterTypeDescription
seller_typestring"dealer" (default), "fsbo", "auction"
dealer_idstringSpecific dealer ID
dealer_typestring"franchise" or "independent"
mc_dealership_group_namestringDealership group name filter
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

ParameterTypeDescription
high_value_featuresstringFilter by high-value features (intersection). Always discover values with facets first: facets="high_value_features|0|1000"
options_packagesstringFilter by installed packages. Discover with: facets="options_packages_mv|0|1000"

Carfax Filters

ParameterTypeDescription
carfax_1_ownerstringOne-owner vehicle
carfax_clean_titlestringClean ownership records

Analytics & Facets

ParameterTypeDescription
facetsstringDiscover unique values and counts. Syntax: "field|offset|limit|min_count"
statsstringGenerate statistics for fields (e.g., "price,miles,dom")
range_facetsstringNumeric range facets

Sorting & Pagination

ParameterTypeDefaultDescription
sort_bystring—Sort field (e.g., price, miles, dom, dist)
sort_orderstring"asc""asc" or "desc"
rowsint5Results to return (max 50)
startint0Pagination offset

Response Control (MCP-only)

ParameterTypeDefaultDescription
fetch_all_photosboolfalseReturn all photos vs. single photo per listing
include_dealer_objectboolfalseInclude full dealer details
include_mc_dealership_objectboolfalseInclude MarketCheck dealership metadata
include_build_objectboolfalseInclude full vehicle build/specs

Use Cases

Search for EVs in California under $50K

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

Discover available makes for SUVs

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

Find low-mileage certified vehicles

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

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

Dealer inventory lookup

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

See Also