---
title: "Get time to sell for comparable vehicles"
method: GET
path: "/time-to-sell"
tags: ["Market"]
---

# Get time to sell for comparable vehicles

`GET /time-to-sell`

How long comparable listings stay on the market: a median days-on-market figure with 25th/75th percentiles. Derived from listing disappearance across scraped marketplaces — a listing unseen for 21+ days before its own source's latest crawl counts as sold, over a 12-month cohort window, with a floor of 30 delisted comparables behind every figure.

**This is a market-liquidity signal, not a sales record.** Delisting also captures withdrawn and expired ads, so the number reads as "how long this kind of car stays on the market", and any figure you surface to an end user should be framed that way.

**Reading the three numbers.** The distribution is right-skewed: a few cars sell almost immediately and a long tail lingers, so the median is not a countdown and the average would be worse. Quote `medianDaysToSell` as the typical wait, `p25Days` as the realistic fast case and `p75Days` as the slow case — a quarter of cars take longer than p75 and the tail beyond it is open-ended. The p25→p75 spread covers the middle half of the cohort and is typically 4-6x wide (a Škoda Octavia in CZ: 10 / 24 / 58 days), which is why publishing the median alone overstates how predictable the wait is.

Send point values for one concrete car: `year`, `kw` and `mileage` are widened server-side (±2 years, ±20%, ±25% respectively). When a cohort still holds fewer than 30 delisted comparables, filters are progressively relaxed (mileage, then kw, then year to ±4) before the request 404s; `fuel` is never relaxed. A 404 means the market genuinely lacks comparable delistings even after relaxation — an expected outcome for rare cars, carrying a `hint` naming the filter to drop, not an error to retry. The country list is deliberately narrower than /vehicle-valuation: a market also needs enough delistings and a fine enough crawl cadence to resolve a listing's lifetime.

## Query parameters

- `make` string, required
- `model` string, required
- `country` 'CZ' | 'SK' | 'PL' | 'UK' | 'US' | 'DE' | 'NL' | 'NO' | 'IT' | 'BE' | 'ES' | 'AT' | 'FR', required
- `year` integer
- `kw` integer
- `mileage` integer
- `fuel` 'petrol' | 'diesel' | 'electric' | 'hybrid' | 'lpg' | 'cng' | 'hydrogen'

## Response `200`

Days-on-market statistics for the cohort actually measured. If a filter had to be relaxed to reach the sample floor, the figures describe the relaxed cohort.

- TimeToSellResponse — Three numbers describing how long the cohort stays on the market, plus the cohort they describe. Read `medianDaysToSell` with `p25Days`/`p75Days` — the distribution is right-skewed and wide, so the median alone overstates how predictable the wait is.
  - `make` string, required — The canonical make the cohort was resolved to — may differ from what you sent (aliases are resolved, e.g. volkswagen → vw)
  - `model` string, required — Model actually queried, in normalized form — may differ from the request
  - `country` string, required — Market the figures describe
  - `medianDaysToSell` integer, required — Median days on market: half of comparable listings left the market faster than this, half slower. The headline number, and the one to quote if you only quote one.
  - `p25Days` integer, required — 25th percentile — the fast quarter. A quarter of comparable listings were gone within this many days, so it reads as the realistic best case for a well-priced, well-presented car rather than a typical outcome.
  - `p75Days` integer, required — 75th percentile — the slow quarter starts here. Three quarters of comparable listings were gone by this point, and the remaining quarter took longer still (the tail is open-ended). Use it for the pessimistic case: p25→p75 is the range that covers the middle half of cars, and it is typically 4-6x wide, which is why the median is not worth publishing on its own.

## Other responses

- `400` — Missing make/model/country, unsupported country or fuel type, or a numeric filter out of range
- `403` — Invalid or missing API key, suspended account, or inactive subscription
- `404` — Fewer than 30 comparable delistings even after the full relaxation ladder. Expected for rare cars; the body carries a hint naming the filter to drop.
- `429` — Monthly quota exhausted or per-minute rate limit exceeded. Quota responses carry resetDate; rate-limit responses carry a Retry-After header.
- `503` — Upstream market-data service unreachable or timed out

## Changes

- **2026-08-10** `cf1d4e12baca` — 9 info
  - added the non-success response with the status `403`
  - added the non-success response with the status `429`
  - removed the non-success response with the status `401`
  - added the optional property `code` to the response with the `400` status
  - …5 more

[Change history](https://skmtc.dev/carapi/apis/carapi-dev-automotive-data-api/changes/time-to-sell/get.md)

---

[API](https://skmtc.dev/carapi/apis/carapi-dev-automotive-data-api.md) · [All operations](https://skmtc.dev/carapi/apis/carapi-dev-automotive-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/carapi/carapi-dev-automotive-data-api/revisions/cf1d4e12baca/schema)