The market days supplyendpoint
GET /v1_2/listings/mds answers one question: how long is this year, make and model sitting? Send year, make and model, add an optional state, and get back the count of active listings plus a full days_on_market distribution - count, min, max, mean, median, p25 and p75. It is a scan call at 10 millicredits.
What does the market days supply endpoint return?
GET /v1_2/listings/mds returns a days-on-market snapshot for one year, make and model across the live catalog. year, make and model are all required; state is optional and narrows the answer to a single market, for example TX. The response keeps its own shape rather than the data plus meta envelope the list routes use: it echoes year, make, model and state, reports active_listings as the count currently advertised, and gives days_on_market as a distribution carrying count, min, max, mean, median, p25 and p75. It also names the method behind the numbers, so the basis is never implicit. Median and the p25-to-p75 spread are the figures to read; the mean is dragged upward by a long tail of stale listings. Market days supply is scan class at 10 millicredits, which is 100 calls per credit.
It measures what we have observed
The distribution is built from listings currently active in the catalog, and the response names its own basis in a method field - read that field rather than assuming a definition. What follows from it either way: a nameplate we have been watching for months and one that entered the catalog last week are not measuring the same window, so compare like with like, and treat a thin active_listings count as a reason to widen the query rather than a finding.
Read the median and the quartiles, not the mean
A distribution with a median of 33 days and a p75 of 61 says something quite different from its own mean of 41.7, because a handful of units sitting past 200 days pull the average up and leave the median untouched. The p25-to-p75 band is the honest picture of how a nameplate is moving, and it is the comparison that survives being quoted next to another market.
Scope to a state before drawing a conclusion
Leave state off and the answer spans the whole US and Canada catalog, mixing markets that behave nothing alike. Add state=TX or state=ON and both active_listings and the distribution narrow to that market. The national figure is a useful baseline to compare against; it is rarely the number a regional buyer or a single dealer group should act on.
One flat charge, no rows to count
The route is priced in the scan class at 10 millicredits because it reads across the catalog, even though it returns one small object rather than a page of listings. That is 100 days-supply calls to a credit whether the cohort holds 40 listings or 40,000. No subscription, and a call that errors is refunded.
Frequently asked questions
What is market days supply in the vehicle listings API?
It is a days-on-market snapshot for one year, make and model, returned by GET /v1_2/listings/mds. The response gives active_listings, the number currently advertised, alongside a days_on_market distribution containing count, min, max, mean, median, p25 and p75. The optional state parameter scopes both figures to one market, and the route reports the method it used to produce them.
What parameters does the market days supply endpoint require?
year, make and model are required, and a missing or mistyped one answers 400 invalid_query. state is optional and takes a code such as TX or ON. make and model match the catalog's own raw values, so pull the exact spelling from GET /v1_2/listings/taxonomy/terms or the autocomplete route rather than guessing at capitalisation or punctuation.
Is this the same as a dealer's own days in stock?
No. This is measured across advertised listings, from when a vehicle first appeared in our catalog through to its most recent sighting, so it is a market-level view of how long a nameplate sits on retail sites. A dealership's internal days in stock starts at acquisition and lives in its DMS. The two move together but they are not the same measurement, and only the API's version can be computed for competitors as easily as for yourself.
How much does a market days supply call cost?
10 millicredits, the same scan-class charge as a search, which is 100 calls per credit. The cost does not move with the size of the cohort or the market you scope it to. Errors are never billed, and the whole listings API bills per call from one shared credit balance with no subscription behind it.
More vehicle listings
Try Hermes Data for $0.99
Self-serve access to the automotive data your business runs on. The $0.99 trial gives you 20 credits to spend across Contacts, Dealers, and Dealer Groups. Then auto-upgrade to Starter ($99/mo) — or cancel any time.
Contacts, Dealers, and Dealer Groups are all self-serve on one credit wallet — spend your trial credits on any of them. Vehicle Listings is live too, on its own API subscription (separate from the credit wallet). Explore Listings.