---
title: "Year Make Model Options"
method: GET
path: "/v1/ymm-options"
tags: ["Year Make Model"]
---

# Year Make Model Options

`GET /v1/ymm-options`

## Request

- Base URL: `https://api.carsxe.com`
- URL: `https://api.carsxe.com/v1/ymm-options`
- Auth: one of:
  - API key in query parameter `key`
  - API key in header `PAYMENT-SIGNATURE`
  - none
- TypeScript: <https://skmtc.dev/carsxe/apis/carsxe-api/docs/v1/ymm-options/get.ts> (a function with typed inputs; its response is checked against the schema)

Populate Year, Make, Model, and Variant dropdown menus. Each response returns exactly one layer. `dimension` is optional — when omitted, the response shape is inferred from `make`/`model`/`year`. Billing: ordinary successful lookups use 1 credit. `dimension=variants` with `year` + `make` (no `model`) uses 1 credit per distinct model returned; the response includes `modelCount`. Required filters help you get better, more relevant results. `year`, `make`, and `model` can be combined for reversed lookups (e.g. years for a given make+model). Successful responses use a minimum of 1 credit even when no models match. Failed requests do not use credits.

## Query parameters

- `dimension` 'years' | 'makes' | 'models' | 'trims' | 'variants'
- `year` string
- `make` string
- `model` string
- `trim` string

## Response `200`

Distinct values for the requested (or inferred) dimension(s).

- object
  - `success` boolean
  - `input` object
  - `message` string: Optional guidance when the returned layer differs from the requested dimension or when explaining how to get better results.
  - `years` integer[]
  - `makes` string[]
  - `models` string[]
  - `trims` string[]
  - `variants` string[]
  - `modelCount` integer: Present only for bulk variants (`dimension=variants` + year + make, no model). Number of distinct models returned. Successful bulk variants use 1 credit per distinct model. Successful responses use a minimum of 1 credit even when no models match. Failed requests do not use credits.

## Other responses

- `400`: Invalid dimension, invalid year, missing required filters, or model without make/year.
- `401`: Missing API key, unknown/disabled API key, or inactive account.
- `429`: API usage limit exceeded for the current billing period.
- `500`: Could not fetch data.

## Changes

- **2026-08-19** `d90c24450642`: 1 info
  - added the optional property `modelCount` to the response with the `200` status
- **2026-08-12** `0ad387c61d41`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/carsxe/apis/carsxe-api/changes/v1/ymm-options/get.md)

---

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