# 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](/docs/precision), 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](/docs/reference/valuations). 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](/docs/reference/market).

## Request

The request body is the same as a [valuation's](/docs/valuations#anatomy-of-a-request). Send `pricing.asking_price` to get the forecast at that price as well:

```json
{
  "country": "SE",
  "vehicle": {
    "make": "Volvo",
    "model": "XC60",
    "model_year": 2019,
    "mileage": { "value": 9000, "unit": "mil" },
    "fuel": "diesel",
    "transmission": "automatic"
  },
  "pricing": { "asking_price": 289000 }
}
```

**curl**

```bash
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
```

**Ruby**

```ruby
require "json"
require "net/http"

uri = URI("https://data-services.autouncle.com/v1/selling-times")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "selling-time-001"
request.body = JSON.generate({
  "country" => "SE",
  "vehicle" => {
    "make" => "Volvo",
    "model" => "XC60",
    "model_year" => 2019,
    "mileage" => {
      "value" => 9000,
      "unit" => "mil"
    },
    "fuel" => "diesel",
    "transmission" => "automatic"
  },
  "pricing" => {
    "asking_price" => 289000
  }
})
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.pretty_generate(JSON.parse(response.body))
```

**Python**

```python
import json
import os

import requests

response = requests.post(
    "https://data-services.autouncle.com/v1/selling-times",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
        "Idempotency-Key": "selling-time-001",
    },
    json={
        "country": "SE",
        "vehicle": {
            "make": "Volvo",
            "model": "XC60",
            "model_year": 2019,
            "mileage": {
                "value": 9000,
                "unit": "mil"
            },
            "fuel": "diesel",
            "transmission": "automatic"
        },
        "pricing": {
            "asking_price": 289000
        }
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))
```

**JavaScript**

```javascript
const response = await fetch("https://data-services.autouncle.com/v1/selling-times", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "selling-time-001",
  },
  body: JSON.stringify({
    country: "SE",
    vehicle: {
      make: "Volvo",
      model: "XC60",
      model_year: 2019,
      mileage: {
        value: 9000,
        unit: "mil"
      },
      fuel: "diesel",
      transmission: "automatic"
    },
    pricing: {
      asking_price: 289000
    }
  }),
});
console.log(JSON.stringify(await response.json(), null, 2));
```

## 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`](/docs/reference/valuations) returns for the same input, and the same valuation ID reads it back with `GET /v1/valuations/{id}`.

```json
{
  "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](/docs/concepts/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`](/docs/reference/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](/docs/valuations#comparable-listings) and a [trade-in price](/docs/valuations#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](/docs/credits).

## MCP

Agents use the `forecast_selling_time` tool, which takes the same arguments as `valuate_car`. See the [tool reference](/docs/mcp/tools).
