---
title: "Filter variants"
method: GET
path: "/variants"
tags: ["variants"]
---

# Filter variants

`GET /variants`

## Request

- Base URL: `https://api.cars-data.com/v1`
- URL: `https://api.cars-data.com/v1/variants`
- Auth: one of:
  - API key in header `X-Api-Key`
  - HTTP bearer
  - none

Structured filtering. Paginated with a **keyset** cursor, not an
offset: `links.next` carries an opaque `c_…` token to hand back as
`?cursor=`. Page size is capped at 50.

Not part of the demo tier.

## Query parameters

- `locale` 'ar' | 'bg' | 'cs' | 'da' | 'de' | 'el' | 'en' | 'es' | 'fr' | 'hr' | 'hu' | 'it' | 'no' | 'pl' | 'pt' | 'ro' | 'sk' | 'sr' | 'sv' | 'tr'
- `cursor` string
- `limit` integer
- `fuel` string
- `body` string
- `drive` string
- `power_min` integer
- `power_max` integer
- `price_max` integer
- `year` integer
- `ev` boolean

## Headers

- `PAYMENT-SIGNATURE` string

## Response `200`

OK. Paid with x402, it also carries `PAYMENT-RESPONSE`.

- VariantListEnvelope
  - `data` Variant[]
    - `accel_0_100_s` number, nullable
    - `battery_kwh` number, nullable
    - `body_type_en` string, nullable
    - `display_name` string
    - `fuel_slug` string, nullable
    - `generation_id` string
    - `power_hp` integer, nullable
    - `price_new_eur` integer, nullable
    - `top_speed_kmh` integer, nullable
    - `torque_nm` integer, nullable
    - `variant_id` string
  - `links` Links
    - `next` string, nullable: Opaque cursor for the next page; absent when the page was not full.
  - `meta` Meta
    - `last_synced_at` string, date-time, required
    - `locale` string
    - `units` 'metric' | 'imperial'

## Other responses

- `401`: No key, or a key we do not know. `WWW-Authenticate: Bearer` on the MCP surface. The MCP server needs no key at all; a REST demo key is one click away. On the two x402 routes a request with no key gets `402` instead, with the price.
- `402`: No key and no valid payment. The price and how to pay are in the `PAYMENT-REQUIRED` header; the body says the same in words. A request that sent a key never gets this — it gets `401`/`403` instead.
- `403`: The key is revoked or not yet active, or — on a demo key — the path is outside the demo tier. The detail says which, and carries the upgrade path.
- `429`: A limit on **your** key: per-minute, per-day or per-month. The detail names which. Distinct from `503`, which is a failure on our side.

---

[API](https://skmtc.dev/cars-data/apis/cars-data-com-api.md) · [All operations](https://skmtc.dev/cars-data/apis/cars-data-com-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cars-data/apis/cars-data-com-api/revisions/4aeb6b2b5c5f?raw)