Skip to content
Concepts / Selling-time forecastsView Markdown ↗
Beta

AutoUncle Data Services is in beta. The API, MCP tools and agent skill may change often, including breaking changes, until version 1.0. Read the changelog before you upgrade an integration.

Selling-time forecasts

POST /v1/selling-times values a vehicle and forecasts how long it takes to sell if it is listed now and its asking price is kept. You get the forecast for an asking price in each price-rating band, so you can see how much faster a sharper price sells, and at your own asking price when you send one. Every field is in the valuations reference. For the market around a car type (how many are on sale, how fast they leave the market, days of supply and a 12-month trend), use market & demand.

Request

The request body is the same as a valuation's. Send pricing.asking_price to get the forecast at that price as well:

{
  "country": "SE",
  "vehicle": {
    "make": "Volvo",
    "model": "XC60",
    "model_year": 2019,
    "mileage": { "value": 9000, "unit": "mil" },
    "fuel": "diesel",
    "transmission": "automatic"
  },
  "pricing": { "asking_price": 289000 }
}
curl https://data-services.autouncle.com/v1/selling-times \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: selling-time-001' \
  -d @- <<'JSON'
{
  "country": "SE",
  "vehicle": {
    "make": "Volvo",
    "model": "XC60",
    "model_year": 2019,
    "mileage": {
      "value": 9000,
      "unit": "mil"
    },
    "fuel": "diesel",
    "transmission": "automatic"
  },
  "pricing": {
    "asking_price": 289000
  }
}
JSON

Result

The result is a valuation with one extra section, selling_time. Everything else (valuation, precision, price_ratings, notes and attributions) is exactly what POST /v1/valuations returns for the same input, and the same valuation ID reads it back with GET /v1/valuations/{id}.

{
  "selling_time": {
    "synthetic": false,
    "currency": "SEK",
    "by_price_rating": [
      { "rating": 5, "label": "Super price", "example_price": 268000, "median_days": 16,
        "chance_sold_within": { "days_30": 0.75, "days_60": 0.9, "days_90": 0.95 } },
      { "rating": 4, "label": "Good price", "example_price": 279000, "median_days": 19,
        "chance_sold_within": { "days_30": 0.7, "days_60": 0.85, "days_90": 0.9 } },
      { "rating": 3, "label": "Fair price", "example_price": 290000, "median_days": 29,
        "chance_sold_within": { "days_30": 0.5, "days_60": 0.75, "days_90": 0.85 } },
      { "rating": 2, "label": "A bit expensive", "example_price": 301000, "median_days": 41,
        "chance_sold_within": { "days_30": 0.35, "days_60": 0.6, "days_90": 0.75 } },
      { "rating": 1, "label": "Expensive", "example_price": 312000, "median_days": 47,
        "chance_sold_within": { "days_30": 0.3, "days_60": 0.55, "days_90": 0.7 } }
    ],
    "at_asking_price": { "asking_price": 289000, "rating": 3, "label": "Fair price", "median_days": 29,
                         "chance_sold_within": { "days_30": 0.5, "days_60": 0.75, "days_90": 0.85 } }
  }
}
Field Meaning
by_price_rating One forecast per price-rating band, from 5 (super price) to 1 (expensive). example_price is the asking price the forecast is for, in the middle of the band, rounded to three significant figures. The band limits are in price_ratings.bands.
at_asking_price The forecast at pricing.asking_price, rated as in price_ratings.asking_price_rating. null when you send no asking price.
median_days Days after listing by which half of comparable vehicles are expected to have sold, in whole days. null when fewer than half are expected to sell within 26 weeks, the period a forecast covers.
chance_sold_within The chance, from 0 to 1 in steps of 0.05, that the vehicle has sold within 30, 60 and 90 days.
synthetic true for a test-key forecast.

How to read a forecast

  • It is for a vehicle listed now at a price that is kept. Real listings are often repriced. A vehicle that is cut from "expensive" to "fair price" after a few weeks sells faster than the "expensive" forecast says.
  • "Sold" means the listing left the market. A listing that is withdrawn without a sale counts as sold, as in every selling-time figure based on listings.
  • Long-standing vehicles. Forecasts are less reliable for vehicles that stay on the market for more than about six months.
  • It is a forecast, not a promise. A selling_time_is_forecast note in notes says so; show it with the figures. The forecast comes from AutoUncle's selling-time model, attributed as autouncle_selling_time_model with role selling_time_model.
  • It never changes the valuation. The forecast is made from the finished valuation.

Markets

Selling-time forecasts are available in every Data Services market: the 14 markets with general availability on markets. Only a country Data Services does not serve to every workspace, such as Belgium (on_request), is refused with selling_time_unsupported_market (a problem document) before any credit is reserved, and nothing is recorded; use POST /v1/valuations there.

If a market's forecast model is temporarily missing, the request fails with selling_time_unavailable (503) and nothing is charged. Retry later with a new idempotency key.

Credits

A successful live forecast costs two credits: one for the valuation and one for the forecast, itemised in usage.charges as {"base": 1, "selling_time": 1}. The credits are reserved together, so a single credit grant must hold both. Comparable listings and a trade-in price requested with options.include cost their extra credit here too, when they are returned.

  • If the vehicle cannot be valued, the request is refused or failed as a valuation would be, and nothing is charged.
  • If the vehicle is valued but the forecast cannot be made, the whole request failed with selling_time_unavailable (503) or selling_time_timeout (504) and nothing is charged. Retry later with a new idempotency key.
  • Test keys return fixed synthetic forecasts (synthetic: true) for free, in the same markets as live keys.

See credits & billing.

MCP

Agents use the forecast_selling_time tool, which takes the same arguments as valuate_car. See the tool reference.