Time to Sell

How long comparable listings stay on the market — median days on market, with the fast and slow quarters

GET Request

~5ms cached, up to ~7s cold

1 credit per request

Endpoint

GET https://api.carapi.dev/v1/time-to-sell

The natural companion to Vehicle Valuation: valuation answers what is it worth, this answers how fast will it move.

How the number is derived

•Every listing is re-sighted on each crawl of its marketplace. A listing that stops being re-sighted has left the market, and the time it was visible is its days on market.
•Sold proxy: a listing unseen for 21+ days before its own source's latest crawl. Anchoring to the source rather than wall-clock time stops a stalled scraper from declaring its whole inventory sold.
•Cohort window: listings first seen in the last 12 months. Listings never re-sighted, and listings with no price, are excluded.
•Sample floor: at least 30 delisted comparables. Below that, filters are progressively relaxed (mileage → kw → year widened to ±4) before the request 404s. fuel is never relaxed.
•Sources: up to 7 marketplaces per market, depending on the country. A figure is always pooled across every source that carries the cohort.

Query Parameters

Parameter	Type	Required	Description
make	string	Required	Vehicle manufacturer, 1-50 characters (case-insensitive). Common aliases are resolved for you (volkswagen → vw).
model	string	Required	Vehicle model, 1-100 characters. Matched as a base model — A6 and A6 Allroad are different cohorts. Trim codes are folded to their series (320d → 3-series).
country	enum	Required	ISO 3166-1 alpha-2 market code. 13 supported: CZ, SK, PL, UK, US, DE, NL, NO, IT, BE, ES, AT, FR.
year	integer	Optional	Model year, 1990 to next year. Widened to ±2 years to keep the sample usable.
kw	integer	Optional	Engine power in kW, 1-2000. Widened to ±20% (at least ±15 kW).
mileage	integer	Optional	Mileage in km, 0-2,000,000. Widened to ±25% (at least ±20,000 km).
fuel	enum	Optional	petrol, diesel, electric, hybrid, lpg, cng, or hydrogen. Matched exactly and never relaxed.
token	string	Required	API authentication token.

Send the one concrete car you care about — the buffers above exist because near-identical cars sell at similar speeds. Exact matching starves the sample: a 2021 Audi RS6 in CZ has 6 delisted comparables on its own, but 34 across the ±2-year band.

Request Examples

cURL

curl -X GET \
  "https://api.carapi.dev/v1/time-to-sell?make=skoda&model=octavia&country=CZ&token=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  token: 'YOUR_API_KEY',
  make: 'audi',
  model: 'a6',
  country: 'CZ',
  year: '2018',
  kw: '180',
  mileage: '120000',
  fuel: 'diesel'
});

const response = await fetch(
  `https://api.carapi.dev/v1/time-to-sell?${params.toString()}`
);
const data = await response.json();
console.log(
  `Typically ${data.medianDaysToSell} days — ` +
  `fast quarter ${data.p25Days}, slow quarter ${data.p75Days}+`
);

Python

import requests

response = requests.get(
    "https://api.carapi.dev/v1/time-to-sell",
    params={
        "token": "YOUR_API_KEY",
        "make": "audi",
        "model": "a6",
        "country": "CZ",
        "year": 2018,
        "kw": 180,
        "mileage": 120000,
        "fuel": "diesel",
    },
)
print(response.json())

Response Examples

Whole model in one market (200)

make, model and country only — every Octavia in CZ, the broadest cohort you can ask for.

{
  "make": "skoda",
  "model": "octavia",
  "country": "CZ",
  "medianDaysToSell": 24,
  "p25Days": 10,
  "p75Days": 58
}

One concrete car (200)

A 2021 RS6, sent as year=2021&kw=441. The body has the same shape whatever you filter on — the optional parameters change which cars the numbers describe, not what comes back.

{
  "make": "audi",
  "model": "rs6",
  "country": "CZ",
  "medianDaysToSell": 39,
  "p25Days": 13,
  "p75Days": 79
}

Not enough comparables (404)

{
  "error": "Insufficient market data for this vehicle configuration",
  "hint": "Try a broader query — omit mileage, kw or year, or use a market with more listings"
}

Response Fields

Field	Type	Description
make / model / country	string	The canonical cohort the query resolved to — may differ from what you sent (aliases and trim codes are resolved, e.g. volkswagen → vw, 320d → 3-series)
medianDaysToSell	number	Median days on market: half of comparable listings left the market faster than this, half slower. The headline number — quote this one if you quote only one
p25Days	number	25th percentile — the fast quarter. A quarter of comparable listings were gone within this many days. Read it as the realistic best case for a sharply priced, well-presented car, not as a typical outcome
p75Days	number	75th percentile — where the slow quarter begins. Three quarters were gone by this point; the remaining quarter took longer still, with no upper bound. Read it as the pessimistic case

Reading the three numbers

Days-on-market is right-skewed: a handful of cars go almost immediately, most take a few weeks, and a long tail sits unsold for months. That shape is why the response gives you three points on the distribution instead of a single average — an average would be dragged upward by the tail and describe no car in particular.

Field	Octavia / CZ	What it means
p25Days	10	A quarter of comparable listings were gone within 10 days. The fast quarter — a realistic best case for a sharply priced, well-presented car.
medianDaysToSell	24	Half were gone within 24 days, half took longer. The typical car — this is the number to lead with.
p75Days	58	Three quarters were gone by day 58 — so a quarter were still listed. The slow quarter starts here, and it has no upper bound.

Read together: p25Days to p75Days is the middle half of the cohort — 10 to 58 days for an Octavia in CZ. That spread is normally 4-6× wide, and it is the honest version of the answer. A lone median reads like a promise the data cannot make.

Not a countdown. The percentiles describe a cohort of past listings, not the car in front of you, and they do not decay as it sits on the market. "Day 30 of a 24-day median" does not mean it is overdue — it means it is in the slower half, which a quarter of that cohort also was.

A worked framing that survives contact with an end user: "Cars like this typically sell in about 24 days. A quarter go within 10; a quarter take more than 58."

Market Coverage (13 countries)

Narrower than Vehicle Valuation's 24 markets on purpose. This endpoint needs enough delistings and a crawl cadence fine enough to resolve a listing's lifetime — a market can carry plenty of listings and still be unable to answer the question honestly.

Tier	Countries	Notes
Tier 1	CZ, SK, PL, UK, US, DE	High volume, healthy re-sighting. CZ has the best data quality overall.
Tier 2	NL, NO, IT, BE, ES, AT, FR	Viable but thinner — expect more relaxation and more 404s on niche models.

NL resolution caveat: 41% of Dutch delistings land in a single 6-day bucket — that is the crawl interval, not the market. Treat NL figures as accurate to roughly ±6 days: fine for ranking models against each other, not for precise promises to an end user.

Countries outside the list are rejected with a 400. Some of them (notably RO and SE) carry plenty of listings but re-sight too rarely or too uniformly to produce a meaningful number, and returning a confident-looking wrong answer would be worse than refusing.

Error Codes

400

Bad Request

Missing make/model/country, an unsupported country, an unsupported fuel type, or a numeric filter out of range

403

Forbidden

Invalid or missing API token

404

Insufficient market data

The cohort stayed under 30 delistings even after relaxation. Normal for rare cars — act on the hint and drop a filter rather than retrying the same query

503

Service Unavailable

The upstream market-data service was unreachable or timed out

Important Notes

•This is a market-liquidity signal, not a sales record. Delisting also captures withdrawn and expired ads, so the figure reads as "how long this kind of car stays on the market" — say it that way wherever you surface the number. The response body does not repeat this caveat; it is a property of the endpoint, not of any one answer.
•Publish p25Days and p75Days with the median. The spread is genuinely wide — an RS6 in CZ runs 13 to 79 days — and a lone median oversells the precision.
•Narrow filters can be widened silently. If the cohort you asked for falls under 30 delistings, mileage is dropped first, then kw, then year goes to ±4 — and you get a 200 describing that wider set rather than a 404. Only send the optional filters you actually need, and treat a heavily filtered query as approximate.
•make and model are echoed as the canonical cohort your query resolved to — the numbers describe that cohort, which is why it may not match your input verbatim.
•A 404 is an expected outcome, not a fault: it means the market genuinely does not hold enough comparable delistings. Do not treat it as an error to retry.
•Responses are cached upstream for 24 hours (the underlying cohort for 10 minutes), so a repeat query returns in single-digit milliseconds. A cold cohort can take several seconds.
•Each request consumes 1 API credit from your monthly allowance — including the 404s. Because a 404 is a routine outcome here rather than a fault, budget for it: narrow your query with year/kw/mileage only when you actually need the cohort narrowed.