---
title: "Search listings — ref filters + spec filters"
method: GET
path: "/v2/listings/search"
tags: ["listings"]
---

# Search listings — ref filters + spec filters

`GET /v2/listings/search`

## Request

- Base URL: `https://api.cardog.app`
- URL: `https://api.cardog.app/v2/listings/search`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Filters are entity refs, checked for grammar and then registry membership — an unknown ref returns a 400 naming it, never a silent fuzzy match. Sort: `?sort=<field>&order=<asc|desc>`.

## Query parameters

- `make` string[]
- `model` string[]
- `nano` string[]
- `bodyStyle` string[]
- `fuelType` string[]
- `driveType` string[]
- `transmission` string[]
- `electrification` string[]
- `vehicleType` string[]
- `trim` string[]
- `seller` string[]
- `exteriorColor` string[]
- `interiorColor` string[]
- `year.min` integer
- `year.max` integer
- `price.min` number
- `price.max` number
- `odometer.min` number
- `odometer.max` number
- `lat` number
- `lng` number
- `radius` number
- `verified` boolean
- `createdAfter` string, date-time
- `updatedAfter` string, date-time
- `spec.{attributeId}` string
- `page` integer
- `limit` integer
- `sort` string
- `order` 'asc' | 'desc'

## Response `200`

Listings + pagination + echoed filters

- ListingSearch
  - `listings` object[], required
    - `id` string, required
    - `vin` string, required
    - `price` number, required
    - `currency` string
    - `odometer` number, nullable
    - `year` integer, required
    - `make` string, required
    - `model` string, required
    - `trim` string, nullable
    - `makeRef` string, nullable
    - `modelRef` string, nullable
    - `nano` string, nullable
    - `media` object[]
  - `pagination` object, required
    - `page` integer, required
    - `limit` integer, required
  - `sort` object
    - `field` string
    - `order` string
  - `filters` object, required
    - `ids` string[]
    - `makes` string[]
    - `models` string[]
    - `nanos` string[]
    - `bodyStyles` string[]
    - `fuelTypes` string[]
    - `driveTypes` string[]
    - `transmissions` string[]
    - `electrificationLevels` string[]
    - `vehicleTypes` string[]
    - `trims` string[]
    - `saleTypes` string[]
    - `sellers` string[]
    - `year` object
      - `min` number
      - `max` number
    - `price` object
      - `min` number
      - `max` number
    - `odometer` object
      - `min` number
      - `max` number
    - `cylinders` object
      - `min` number
      - `max` number
    - `doors` object
      - `min` number
      - `max` number
    - `exteriorColors` string[]
    - `interiorColors` string[]
    - `location` object
      - `lat` number, required
      - `lng` number, required
      - `radius` number, required
    - `verified` boolean
    - `createdAfter` string, date-time
    - `updatedAfter` string, date-time
    - `spec` object: Spec filters keyed by attribute id (see GET /v2/specs/catalog). Numeric attributes take a {min, max} range; equipment attributes take availability values ("standard", "optional", "unavailable"). Example: {"fuelEconomyCombined": {"min": 35}, "heatedSeatsFront": ["standard"]}

## Other responses

- `400`: Invalid request — grammar failure or unknown-but-well-formed refs, NAMED in `refs`/`details`, with nearest-ref `suggestions` where computable. Never a fuzzy fallback.
- `401`: No valid credential (API key, session, or internal token)
- `402`: Insufficient credits (free-tier hard stop; paid tiers bill overage instead)
- `429`: Per-minute rate limit exceeded
- `500`: Internal error

---

[API](https://skmtc.dev/cardog/apis/cardog-api-v2.md) · [All operations](https://skmtc.dev/cardog/apis/cardog-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/cardog/apis/cardog-api-v2/revisions/b9d48193126f?raw)