---
title: "Facets over the filtered set — (ref, name, count) buckets"
method: GET
path: "/v2/listings/facets"
tags: ["listings"]
---

# Facets over the filtered set — (ref, name, count) buckets

`GET /v2/listings/facets`

## Request

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

## 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

## Response `200`

Ref-native facets, feature facets, ranges, histogram

- ListingFacets
  - `makes` object[], required
    - `ref` string, required
    - `name` string, required
    - `count` integer, required
    - `parentRef` string
  - `models` object[], required
    - `ref` string, required
    - `name` string, required
    - `count` integer, required
    - `parentRef` string
  - `bodyStyles` object[], required
    - `ref` string, required
    - `name` string, required
    - `count` integer, required
    - `parentRef` string
  - `fuelTypes` object[], required
    - `ref` string, required
    - `name` string, required
    - `count` integer, required
    - `parentRef` string
  - `driveTypes` object[], required
    - `ref` string, required
    - `name` string, required
    - `count` integer, required
    - `parentRef` string
  - `transmissions` object[], required
    - `ref` string, required
    - `name` string, required
    - `count` integer, required
    - `parentRef` string
  - `electrificationLevels` object[], required
    - `ref` string, required
    - `name` string, required
    - `count` integer, required
    - `parentRef` string
  - `vehicleTypes` object[], required
    - `ref` string, required
    - `name` string, required
    - `count` integer, required
    - `parentRef` string
  - `exteriorColors` object[], required
    - `ref` string, required
    - `name` string, required
    - `count` integer, required
    - `parentRef` string
  - `saleTypes` object[], required
    - `ref` string, required
    - `name` string, required
    - `count` integer, required
    - `parentRef` string
  - `years` object
    - `min` number, required
    - `max` number, required
  - `prices` object
    - `min` number, required
    - `max` number, required
  - `odometer` object
    - `min` number, required
    - `max` number, required
  - `priceHistogram` object[]
    - `min` number, required
    - `max` number, required
    - `count` number, required
  - `featureFacets` object[]
    - `id` string, required
    - `name` string, required
    - `category` 'tech' | 'comfort' | 'safety' | 'ev', required
    - `count` integer, required
  - `specRanges` object
  - `featureFacetsAreApproximate` boolean
  - `totalCount` integer, required
  - `totalCountIsApproximate` boolean

## 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)