# Valuations

Create a valuation for one vehicle in one market, and read back a recorded result. Field tables on this page are generated from the [OpenAPI contract](/openapi.yaml), so they always match what the API validates.

> **Note:** Since contract 0.9.0, `vehicle` in a result is an [AutoUncle Vehicle Schema (AVS)](https://github.com/AutoUncle/avs) 0.3 vehicle document, with the catalogue identification and per-value provenance beside it in [`identification`](/docs/reference/vehicles#identification). `vehicle` in a request is a [VehicleInput](/docs/reference/vehicles#vehicleinput-describing-a-vehicle): that AVS document, or the vehicle's attributes. See the [changelog](/docs/changelog).

## POST /v1/valuations

Resolve and value a vehicle.

One credit per successful live valuation, plus one when requested comparable listings are returned, one when a requested trade-in price is returned and one when sent photos were used. Retry an unknown network outcome with the original Idempotency-Key and identical input. A confirmed recorded success, refusal or failure outcome is replayed; use a new key to execute a fresh attempt after a confirmed refusal or failure. Optional AI resolution is deployment-configured; warnings identify unused input. Sandbox never calls AI. Concurrent valuations are limited per workspace (429 concurrency_limited) and engine-wide or per market (503 engine_busy); these rejections happen before the request is started, carry Retry-After and retry_after, consume no credit and may be retried with the same Idempotency-Key.

- **Scope:** `valuations:write`
- **Cost:** One credit for a successful (`valued`) live valuation, plus one when requested comparables are returned, one when a requested trade-in price is returned and one when sent photos were used. The similar-cars link is free. Test-key valuations, refusals and failures are free.
- **Rate limit:** valuations bucket, default 60 requests per minute. See [limits](/docs/concepts/limits).

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | No | Workspace- and mode-scoped retry key. Unknown network outcome: retry the same key. Confirmed recorded refusal/failure: new key for a fresh attempt. 1 to 200 characters. |

### Request body

`application/json`, at most 1 MB. A [ValuationRequest](/docs/concepts/vehicle#valuation-request-fields): `country` plus at least one of `vehicle`, `description` or `images`. Unknown fields are rejected.

Structured example:

```json
{
  "country": "DK",
  "vehicle": {
    "make": "Volkswagen",
    "model": "Golf",
    "model_year": 2020,
    "mileage": {
      "value": 65000,
      "unit": "km"
    },
    "fuel": "petrol",
    "transmission": "automatic"
  }
}
```

Text example:

```json
{
  "country": "DK",
  "description": "Volkswagen Golf 1.5 TSI DSG, registered 2020, 65000 km"
}
```

Comparables example:

```json
{
  "country": "SE",
  "vehicle": {
    "make": "Volvo",
    "model": "XC60",
    "model_year": 2021,
    "mileage": {
      "value": 6500,
      "unit": "mil"
    },
    "fuel": "plug_in_hybrid_petrol",
    "transmission": "automatic"
  },
  "options": {
    "include": [
      "comparables"
    ]
  }
}
```

Trade in example:

```json
{
  "country": "DE",
  "vehicle": {
    "make": "Volkswagen",
    "model": "Golf",
    "model_year": 2021,
    "mileage": {
      "value": 48000,
      "unit": "km"
    },
    "fuel": "petrol",
    "transmission": "manual"
  },
  "options": {
    "include": [
      "trade_in_price",
      "similar_cars_link"
    ]
  }
}
```

### Response

`application/json`: a [valuation result](/docs/reference/valuations#the-valuation-result). Refused and failed valuations return the same envelope with `status` and a nested `error`, using the error's HTTP status. Errors before a valuation is recorded return a [Problem](/docs/reference/valuations#the-problem-object) as `application/problem+json`.

### Response headers

| Header | Description |
| --- | --- |
| `X-Request-Id` | The HTTP request ID, on every response. Use it to correlate one HTTP exchange in proxy and application logs; it echoes a valid X-Request-Id you send. It is not the valuation ID. |
| `X-Valuation-Id` | The recorded valuation's ID (`val_…`, or `stf_…` for a selling-time forecast), the same value as the body's `request_id`. Present whenever the response is a valuation result, including refused and failed outcomes and idempotent replays. Use it with GET /v1/valuations/{id}, the console and support. |
| `Retry-After` | Seconds to wait before retrying. Present on capacity and rate-limit rejections. |

### Errors

| Code | HTTP | Retryable | Meaning |
| --- | --- | --- | --- |
| [`invalid_request`](/docs/errors#invalid_request) | 400 | No | Send a request matching the documented schema. |
| [`country_required`](/docs/errors#country_required) | 400 | No | Include country, the valuation market, in the request. |
| [`unsupported_country`](/docs/errors#unsupported_country) | 400 | No | Choose a supported ISO country code. |
| [`unauthenticated`](/docs/errors#unauthenticated) | 401 | No | Supply an API key as a Bearer token. |
| [`invalid_api_key`](/docs/errors#invalid_api_key) | 401 | No | Supply a valid AutoUncle Data Services API key. |
| [`key_revoked`](/docs/errors#key_revoked) | 401 | No | This key has expired or been revoked. Create a new key. |
| [`insufficient_credits`](/docs/errors#insufficient_credits) | 402 | No | The organization has no credits available. Contact sales for a package. |
| [`key_spend_limit_reached`](/docs/errors#key_spend_limit_reached) | 402 | No | This API key has reached its monthly credit limit. |
| [`insufficient_scope`](/docs/errors#insufficient_scope) | 403 | No | Use a key with the required scope. |
| [`country_not_enabled`](/docs/errors#country_not_enabled) | 403 | No | This country is not enabled for this organization or key. |
| [`organization_pending`](/docs/errors#organization_pending) | 403 | No | This workspace is waiting for AutoUncle to approve it. |
| [`organization_suspended`](/docs/errors#organization_suspended) | 403 | No | This organization is inactive. Contact support. |
| [`unknown_catalogue_id`](/docs/errors#unknown_catalogue_id) | 404 | No | The catalogue ID is unknown. Fetch current IDs from the catalogue API. |
| [`idempotency_conflict`](/docs/errors#idempotency_conflict) | 409 | No | This idempotency key was used with different input. Choose a new key. |
| [`request_in_progress`](/docs/errors#request_in_progress) | 409 | Yes | A request with this idempotency key is still running. Retry later with the same key. |
| [`payload_too_large`](/docs/errors#payload_too_large) | 413 | No | The request exceeds the maximum supported size of 1 MB. |
| [`missing_mileage`](/docs/errors#missing_mileage) | 422 | No | Supply the actual mileage in vehicle.mileage, or explicitly set options.allow_mileage_estimation to true to use a fixed 96,000 km baseline assumption. |
| [`vehicle_not_identified`](/docs/errors#vehicle_not_identified) | 422 | No | Provide more vehicle attributes or select catalogue IDs. |
| [`catalogue_id_conflict`](/docs/errors#catalogue_id_conflict) | 422 | No | The catalogue IDs do not describe the same vehicle hierarchy. |
| [`vehicle_out_of_range`](/docs/errors#vehicle_out_of_range) | 422 | No | The vehicle is outside the supported valuation range. |
| [`unsupported_vehicle`](/docs/errors#unsupported_vehicle) | 422 | No | This type of vehicle is not supported. |
| [`precision_below_minimum`](/docs/errors#precision_below_minimum) | 422 | No | Provide more attributes or lower the requested minimum precision. |
| [`images_unreadable`](/docs/errors#images_unreadable) | 422 | No | Provide readable supported images. |
| [`rate_limited`](/docs/errors#rate_limited) | 429 | Yes | The request rate limit was reached. Retry after the current minute. |
| [`test_limit_reached`](/docs/errors#test_limit_reached) | 429 | Yes | This workspace has used its fair-use allowance of test-key requests for now. |
| [`concurrency_limited`](/docs/errors#concurrency_limited) | 429 | Yes | Too many valuations are running at the same time for this organization. |
| [`rate_limit_unavailable`](/docs/errors#rate_limit_unavailable) | 503 | Yes | Request limiting is temporarily unavailable. Retry later. |
| [`engine_busy`](/docs/errors#engine_busy) | 503 | Yes | The valuation engine is at capacity. Retry after a short delay. |
| [`engine_unavailable`](/docs/errors#engine_unavailable) | 503 | Yes | The valuation engine is temporarily unavailable. After a confirmed failed response, use a new idempotency key for a fresh attempt. |
| [`engine_misconfigured`](/docs/errors#engine_misconfigured) | 503 | No | The valuation service for this market is not configured correctly. |
| [`engine_timeout`](/docs/errors#engine_timeout) | 504 | Yes | The valuation service did not respond within its time budget. |
| [`engine_invalid_response`](/docs/errors#engine_invalid_response) | 502 | Yes | The valuation service returned an invalid response. |
| [`request_timeout`](/docs/errors#request_timeout) | 504 | Yes | The valuation request exhausted its processing time budget. |
| [`resolution_timeout`](/docs/errors#resolution_timeout) | 504 | Yes | Vehicle interpretation did not finish within its time budget. |
| [`resolution_unavailable`](/docs/errors#resolution_unavailable) | 503 | Yes | Vehicle interpretation is temporarily unavailable. |
| [`resolution_invalid_response`](/docs/errors#resolution_invalid_response) | 502 | Yes | Vehicle interpretation returned an invalid response. |
| [`image_timeout`](/docs/errors#image_timeout) | 504 | Yes | Image retrieval did not finish within its time budget. |
| [`image_unavailable`](/docs/errors#image_unavailable) | 503 | Yes | The image service is temporarily unavailable. |
| [`image_invalid_response`](/docs/errors#image_invalid_response) | 502 | Yes | The image service returned an invalid response. |
| [`internal_error`](/docs/errors#internal_error) | 500 | No | The valuation could not be completed. Contact support with the request ID. |

### Examples

**curl**

```bash
curl https://data-services.autouncle.com/v1/valuations \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: first-valuation-001' \
  -d @- <<'JSON'
{
  "country": "DK",
  "vehicle": {
    "make": "Volkswagen",
    "model": "Golf",
    "model_year": 2020,
    "mileage": {
      "value": 60000,
      "unit": "km"
    }
  }
}
JSON
```

**Ruby**

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

uri = URI("https://data-services.autouncle.com/v1/valuations")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "first-valuation-001"
request.body = JSON.generate({
  "country" => "DK",
  "vehicle" => {
    "make" => "Volkswagen",
    "model" => "Golf",
    "model_year" => 2020,
    "mileage" => {
      "value" => 60000,
      "unit" => "km"
    }
  }
})
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/valuations",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
        "Idempotency-Key": "first-valuation-001",
    },
    json={
        "country": "DK",
        "vehicle": {
            "make": "Volkswagen",
            "model": "Golf",
            "model_year": 2020,
            "mileage": {
                "value": 60000,
                "unit": "km"
            }
        }
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))
```

**JavaScript**

```javascript
const response = await fetch("https://data-services.autouncle.com/v1/valuations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "first-valuation-001",
  },
  body: JSON.stringify({
    country: "DK",
    vehicle: {
      make: "Volkswagen",
      model: "Golf",
      model_year: 2020,
      mileage: {
        value: 60000,
        unit: "km"
      }
    }
  }),
});
console.log(JSON.stringify(await response.json(), null, 2));
```

[Open this request in the console playground](https://data-services.autouncle.com/console/playground?example=valuation)

**curl**

```bash
curl https://data-services.autouncle.com/v1/valuations \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: valuation-catalogue-001' \
  -d @- <<'JSON'
{
  "country": "DK",
  "vehicle": {
    "catalogue": {
      "drivetrain_id": "dv-947a3199394a5a4b41cb2869"
    },
    "model_year": 2021,
    "mileage": {
      "value": 45000,
      "unit": "km"
    }
  },
  "pricing": {
    "price_basis": "dealer_retail"
  }
}
JSON
```

**Ruby**

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

uri = URI("https://data-services.autouncle.com/v1/valuations")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "valuation-catalogue-001"
request.body = JSON.generate({
  "country" => "DK",
  "vehicle" => {
    "catalogue" => {
      "drivetrain_id" => "dv-947a3199394a5a4b41cb2869"
    },
    "model_year" => 2021,
    "mileage" => {
      "value" => 45000,
      "unit" => "km"
    }
  },
  "pricing" => {
    "price_basis" => "dealer_retail"
  }
})
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/valuations",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
        "Idempotency-Key": "valuation-catalogue-001",
    },
    json={
        "country": "DK",
        "vehicle": {
            "catalogue": {
                "drivetrain_id": "dv-947a3199394a5a4b41cb2869"
            },
            "model_year": 2021,
            "mileage": {
                "value": 45000,
                "unit": "km"
            }
        },
        "pricing": {
            "price_basis": "dealer_retail"
        }
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))
```

**JavaScript**

```javascript
const response = await fetch("https://data-services.autouncle.com/v1/valuations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "valuation-catalogue-001",
  },
  body: JSON.stringify({
    country: "DK",
    vehicle: {
      catalogue: {
        drivetrain_id: "dv-947a3199394a5a4b41cb2869"
      },
      model_year: 2021,
      mileage: {
        value: 45000,
        unit: "km"
      }
    },
    pricing: {
      price_basis: "dealer_retail"
    }
  }),
});
console.log(JSON.stringify(await response.json(), null, 2));
```

[Open this request in the console playground](https://data-services.autouncle.com/console/playground?example=valuation_catalogue)

## GET /v1/valuations/{id}

Retrieve your workspace’s recorded valuation.

Returns the result exactly as it was recorded, including its notes and attributions, but without the `usage` block. A test key reads only test-mode results and a live key only live results.

- **Scope:** `valuations:read`
- **Cost:** Free. Counts towards the per-minute valuation rate limit.
- **Rate limit:** valuations bucket, default 60 requests per minute. See [limits](/docs/concepts/limits).

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes | Identifier from a previous response. At most 200 characters. |

### Response

`application/json`: a [valuation result](/docs/reference/valuations#the-valuation-result). Refused and failed valuations return the same envelope with `status` and a nested `error`, using the error's HTTP status. Errors before a valuation is recorded return a [Problem](/docs/reference/valuations#the-problem-object) as `application/problem+json`.

### Response headers

| Header | Description |
| --- | --- |
| `X-Request-Id` | The HTTP request ID, on every response. Use it to correlate one HTTP exchange in proxy and application logs; it echoes a valid X-Request-Id you send. It is not the valuation ID. |
| `X-Valuation-Id` | The recorded valuation's ID (`val_…`, or `stf_…` for a selling-time forecast), the same value as the body's `request_id`. Present whenever the response is a valuation result, including refused and failed outcomes and idempotent replays. Use it with GET /v1/valuations/{id}, the console and support. |

### Errors

| Code | HTTP | Retryable | Meaning |
| --- | --- | --- | --- |
| [`unauthenticated`](/docs/errors#unauthenticated) | 401 | No | Supply an API key as a Bearer token. |
| [`invalid_api_key`](/docs/errors#invalid_api_key) | 401 | No | Supply a valid AutoUncle Data Services API key. |
| [`key_revoked`](/docs/errors#key_revoked) | 401 | No | This key has expired or been revoked. Create a new key. |
| [`insufficient_scope`](/docs/errors#insufficient_scope) | 403 | No | Use a key with the required scope. |
| [`country_not_enabled`](/docs/errors#country_not_enabled) | 403 | No | This country is not enabled for this organization or key. |
| [`organization_pending`](/docs/errors#organization_pending) | 403 | No | This workspace is waiting for AutoUncle to approve it. |
| [`organization_suspended`](/docs/errors#organization_suspended) | 403 | No | This organization is inactive. Contact support. |
| [`not_found`](/docs/errors#not_found) | 404 | No | The requested resource was not found. |
| [`rate_limited`](/docs/errors#rate_limited) | 429 | Yes | The request rate limit was reached. Retry after the current minute. |

### Examples

**curl**

```bash
curl https://data-services.autouncle.com/v1/valuations/val_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY"
```

**Ruby**

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

uri = URI("https://data-services.autouncle.com/v1/valuations/val_0123456789abcdef0123456789abcdef")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
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.get(
    "https://data-services.autouncle.com/v1/valuations/val_0123456789abcdef0123456789abcdef",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))
```

**JavaScript**

```javascript
const response = await fetch("https://data-services.autouncle.com/v1/valuations/val_0123456789abcdef0123456789abcdef", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
  },
});
console.log(JSON.stringify(await response.json(), null, 2));
```

## POST /v1/selling-times

Value a vehicle and forecast its selling time.

Values the vehicle exactly as POST /v1/valuations does and adds selling_time: the expected days to sell, and the chance of selling within 30, 60 and 90 days, for an asking price in the middle of each price-rating band and at pricing.asking_price when it is sent. Available in every Data Services market; a country Data Services does not serve to every workspace (such as BE, on request) is refused with selling_time_unsupported_market, and a market whose forecast model is temporarily missing fails with selling_time_unavailable; neither is charged. Two credits per successful live forecast, one for the valuation (usage.charges.base) and one for the forecast (usage.charges.selling_time), plus any requested add-on such as comparables or a trade-in price; when the forecast cannot be made the request fails (selling_time_unavailable or selling_time_timeout) and nothing is charged. Test keys return fixed synthetic forecasts for free. Idempotency, admission limits and replays work as for valuations, and the result is read back with GET /v1/valuations/{id}.

Available in every Data Services market; only a country Data Services does not serve to every workspace, such as Belgium, is refused with `selling_time_unsupported_market`. When a market's forecast model is temporarily missing, the request fails with `selling_time_unavailable` (503) and nothing is charged. The response is a valuation with `selling_time` added, and the same valuation ID reads it back with GET /v1/valuations/{id}. A credit grant must hold both credits. Counts against the valuation rate limit and needs a valuation concurrency slot, like POST /v1/valuations.

- **Scope:** `valuations:write`
- **Cost:** Two credits for a successful (`valued`) live forecast: one for the valuation and one for the forecast, plus one when requested comparables are returned. Test keys, refusals and failures, including a forecast that could not be made, are free.
- **Rate limit:** valuations bucket, default 60 requests per minute. See [limits](/docs/concepts/limits).

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | No | Workspace- and mode-scoped retry key. Unknown network outcome: retry the same key. Confirmed recorded refusal/failure: new key for a fresh attempt. 1 to 200 characters. |

### Request body

`application/json`, at most 1 MB. A [ValuationRequest](/docs/concepts/vehicle#valuation-request-fields): `country` plus at least one of `vehicle`, `description` or `images`. Unknown fields are rejected.

Structured example:

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

### Response

`application/json`: a [valuation result](/docs/reference/valuations#the-valuation-result). Refused and failed valuations return the same envelope with `status` and a nested `error`, using the error's HTTP status. Errors before a valuation is recorded return a [Problem](/docs/reference/valuations#the-problem-object) as `application/problem+json`.

### Response headers

| Header | Description |
| --- | --- |
| `X-Request-Id` | The HTTP request ID, on every response. Use it to correlate one HTTP exchange in proxy and application logs; it echoes a valid X-Request-Id you send. It is not the valuation ID. |
| `X-Valuation-Id` | The recorded valuation's ID (`val_…`, or `stf_…` for a selling-time forecast), the same value as the body's `request_id`. Present whenever the response is a valuation result, including refused and failed outcomes and idempotent replays. Use it with GET /v1/valuations/{id}, the console and support. |
| `Retry-After` | Seconds to wait before retrying. Present on capacity and rate-limit rejections. |

### Errors

| Code | HTTP | Retryable | Meaning |
| --- | --- | --- | --- |
| [`invalid_request`](/docs/errors#invalid_request) | 400 | No | Send a request matching the documented schema. |
| [`country_required`](/docs/errors#country_required) | 400 | No | Include country, the valuation market, in the request. |
| [`unsupported_country`](/docs/errors#unsupported_country) | 400 | No | Choose a supported ISO country code. |
| [`unauthenticated`](/docs/errors#unauthenticated) | 401 | No | Supply an API key as a Bearer token. |
| [`invalid_api_key`](/docs/errors#invalid_api_key) | 401 | No | Supply a valid AutoUncle Data Services API key. |
| [`key_revoked`](/docs/errors#key_revoked) | 401 | No | This key has expired or been revoked. Create a new key. |
| [`insufficient_credits`](/docs/errors#insufficient_credits) | 402 | No | The organization has no credits available. Contact sales for a package. |
| [`key_spend_limit_reached`](/docs/errors#key_spend_limit_reached) | 402 | No | This API key has reached its monthly credit limit. |
| [`insufficient_scope`](/docs/errors#insufficient_scope) | 403 | No | Use a key with the required scope. |
| [`country_not_enabled`](/docs/errors#country_not_enabled) | 403 | No | This country is not enabled for this organization or key. |
| [`organization_pending`](/docs/errors#organization_pending) | 403 | No | This workspace is waiting for AutoUncle to approve it. |
| [`organization_suspended`](/docs/errors#organization_suspended) | 403 | No | This organization is inactive. Contact support. |
| [`unknown_catalogue_id`](/docs/errors#unknown_catalogue_id) | 404 | No | The catalogue ID is unknown. Fetch current IDs from the catalogue API. |
| [`idempotency_conflict`](/docs/errors#idempotency_conflict) | 409 | No | This idempotency key was used with different input. Choose a new key. |
| [`request_in_progress`](/docs/errors#request_in_progress) | 409 | Yes | A request with this idempotency key is still running. Retry later with the same key. |
| [`payload_too_large`](/docs/errors#payload_too_large) | 413 | No | The request exceeds the maximum supported size of 1 MB. |
| [`missing_mileage`](/docs/errors#missing_mileage) | 422 | No | Supply the actual mileage in vehicle.mileage, or explicitly set options.allow_mileage_estimation to true to use a fixed 96,000 km baseline assumption. |
| [`vehicle_not_identified`](/docs/errors#vehicle_not_identified) | 422 | No | Provide more vehicle attributes or select catalogue IDs. |
| [`catalogue_id_conflict`](/docs/errors#catalogue_id_conflict) | 422 | No | The catalogue IDs do not describe the same vehicle hierarchy. |
| [`vehicle_out_of_range`](/docs/errors#vehicle_out_of_range) | 422 | No | The vehicle is outside the supported valuation range. |
| [`unsupported_vehicle`](/docs/errors#unsupported_vehicle) | 422 | No | This type of vehicle is not supported. |
| [`precision_below_minimum`](/docs/errors#precision_below_minimum) | 422 | No | Provide more attributes or lower the requested minimum precision. |
| [`images_unreadable`](/docs/errors#images_unreadable) | 422 | No | Provide readable supported images. |
| [`rate_limited`](/docs/errors#rate_limited) | 429 | Yes | The request rate limit was reached. Retry after the current minute. |
| [`test_limit_reached`](/docs/errors#test_limit_reached) | 429 | Yes | This workspace has used its fair-use allowance of test-key requests for now. |
| [`concurrency_limited`](/docs/errors#concurrency_limited) | 429 | Yes | Too many valuations are running at the same time for this organization. |
| [`rate_limit_unavailable`](/docs/errors#rate_limit_unavailable) | 503 | Yes | Request limiting is temporarily unavailable. Retry later. |
| [`selling_time_unsupported_market`](/docs/errors#selling_time_unsupported_market) | 422 | No | Selling-time forecasts are not available for this market. |
| [`selling_time_unavailable`](/docs/errors#selling_time_unavailable) | 503 | Yes | The selling-time forecast is temporarily unavailable. |
| [`selling_time_timeout`](/docs/errors#selling_time_timeout) | 504 | Yes | The selling-time forecast did not finish within its time budget. |
| [`engine_busy`](/docs/errors#engine_busy) | 503 | Yes | The valuation engine is at capacity. Retry after a short delay. |
| [`engine_unavailable`](/docs/errors#engine_unavailable) | 503 | Yes | The valuation engine is temporarily unavailable. After a confirmed failed response, use a new idempotency key for a fresh attempt. |
| [`engine_misconfigured`](/docs/errors#engine_misconfigured) | 503 | No | The valuation service for this market is not configured correctly. |
| [`engine_timeout`](/docs/errors#engine_timeout) | 504 | Yes | The valuation service did not respond within its time budget. |
| [`engine_invalid_response`](/docs/errors#engine_invalid_response) | 502 | Yes | The valuation service returned an invalid response. |
| [`request_timeout`](/docs/errors#request_timeout) | 504 | Yes | The valuation request exhausted its processing time budget. |
| [`resolution_timeout`](/docs/errors#resolution_timeout) | 504 | Yes | Vehicle interpretation did not finish within its time budget. |
| [`resolution_unavailable`](/docs/errors#resolution_unavailable) | 503 | Yes | Vehicle interpretation is temporarily unavailable. |
| [`resolution_invalid_response`](/docs/errors#resolution_invalid_response) | 502 | Yes | Vehicle interpretation returned an invalid response. |
| [`image_timeout`](/docs/errors#image_timeout) | 504 | Yes | Image retrieval did not finish within its time budget. |
| [`image_unavailable`](/docs/errors#image_unavailable) | 503 | Yes | The image service is temporarily unavailable. |
| [`image_invalid_response`](/docs/errors#image_invalid_response) | 502 | Yes | The image service returned an invalid response. |
| [`internal_error`](/docs/errors#internal_error) | 500 | No | The valuation could not be completed. Contact support with the request ID. |

### Examples

**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));
```

`POST /v1/selling-times` takes the same request fields as a valuation and returns the same result with `selling_time` added. See [selling-time forecasts](/docs/selling-time).

## Request fields

Every field of the request body. `country` is required, plus at least one of `vehicle` (with at least one attribute), `description` or `images`. Omit what you do not know rather than guessing. `vehicle` takes the vehicle's attributes, listed below, or an AVS vehicle document such as one an endpoint returned ([VehicleInput](/docs/reference/vehicles#vehicleinput-describing-a-vehicle)); [describing a vehicle](/docs/concepts/vehicle) explains how the fields work together.

| Field | Type | Description |
| --- | --- | --- |
| `country` | string | Valuation market as an ISO 3166-1 alpha-2 code, such as DK, DE or GB. The market selects its own vehicle data, currency and mileage conventions. 2 to 10 characters. |
| `vehicle` | object | A vehicle as a request describes it: either an AVS vehicle document (any `vehicle` an endpoint returned, posted back unchanged, or one you build), recognized by its `avs` member, or the vehicle's attributes (VehicleAttributes). Omit unknown values instead of guessing. |
| `vehicle.make` | string | Vehicle manufacturer or make, such as VW or BMW. Catalogue brand_id avoids ambiguous names. At most 200 characters. |
| `vehicle.model` | string | Model name as supplied by your source, such as Golf. Catalogue model_id avoids name mapping and spelling ambiguity. At most 200 characters. |
| `vehicle.variant` | string | Free-text engine, trim or version designation, such as 1.5 TSI DSG. This can help resolve a more precise catalogue identity. At most 200 characters. |
| `vehicle.body` | string | Body style or source label, such as hatchback, estate or SUV. Unknown labels may remain unresolved. At most 200 characters. |
| `vehicle.fuel` | string | Fuel or electrification type: petrol, diesel, electric, hybrid (a full hybrid that cannot be plugged in), plug_in_hybrid_petrol, plug_in_hybrid_diesel, lpg, cng, ethanol or hydrogen, as listed by /v1/catalogue/enums. Source labels are also normalized when recognized. At most 200 characters. |
| `vehicle.color` | string | Exterior colour or colour family from your source. Colour is normalized when possible. At most 200 characters. |
| `vehicle.catalogue` | object | Stable AutoUncle catalogue UUIDs. Supply any known levels; IDs must describe one consistent vehicle hierarchy. |
| `vehicle.catalogue.brand_id` | string | Make UUID returned by the brands catalogue endpoint. All lower-level IDs must belong to this make. 1 to 100 characters. |
| `vehicle.catalogue.model_id` | string | Model UUID returned by the models catalogue endpoint. Virtual model aliases are resolved to their canonical model for scoring. 1 to 100 characters. |
| `vehicle.catalogue.generation_id` | string | Generation UUID returned for the selected model. This identifies the vehicle generation and body variant. 1 to 100 characters. |
| `vehicle.catalogue.drivetrain_id` | string | Drivetrain UUID returned for the selected generation. Identifies the engine and transmission variant and improves identity precision. 1 to 100 characters. |
| `vehicle.catalogue.equipment_variant_id` | string | Equipment or trim variant UUID returned for the make. It must belong to the same make as the other catalogue IDs. 1 to 100 characters. |
| `vehicle.model_year` | integer | Known registration or model year as a four-digit integer. first_registration takes precedence when both are supplied. 1900 to 2100. |
| `vehicle.first_registration` | string (date) | First registration date in YYYY-MM-DD format. The current valuation payload uses its year; do not derive a registration date from a photograph. At most 10 characters. |
| `vehicle.mileage` | object | Odometer value with an explicit unit. Values are converted to the requested market convention before scoring. |
| `vehicle.mileage.value` **required** | number | Non-negative odometer reading in the accompanying unit. Do not convert it twice when changing the unit. 0 to 10000000. |
| `vehicle.mileage.unit` **required** | string | Odometer unit: km means kilometres, mi means miles, and mil means Scandinavian miles of ten kilometres. One of `km`, `mi`, `mil`. |
| `vehicle.transmission` | string | Known transmission type, automatic or manual. Omit it when unknown; an omitted gearbox is not treated as manual. One of `manual`, `automatic`. |
| `vehicle.drive` | string | Driven wheels: fwd, rwd, awd or 4wd, or 2wd when only two-wheel drive is known (the value catalogue drivetrains return for most cars). Use the value supported by the vehicle specification. One of `fwd`, `rwd`, `2wd`, `awd`, `4wd`. |
| `vehicle.power_hp` | number | Engine or drivetrain power in horsepower. Convert a source value in kilowatts before submitting it here. 0 to 3000. |
| `vehicle.engine_size_l` | number | Combustion engine displacement in litres, such as 1.5. Omit for a fully electric vehicle. 0 to 30. |
| `vehicle.battery_kwh` | number | Known traction battery capacity in kilowatt-hours. Omit when the source does not report a capacity. 0 to 500. |
| `vehicle.electric_range_km` | number | Known electric driving range in kilometres, regardless of the odometer unit or valuation market. 0 to 3000. |
| `vehicle.doors` | integer | Number of doors reported by the vehicle specification. Helps distinguish otherwise similar body variants. 1 to 10. |
| `vehicle.seats` | integer | Number of seats reported by the vehicle specification. 1 to 20. |
| `vehicle.condition` | number | Known numeric vehicle condition grade from 0 through 4. Omit unknown condition rather than inventing a grade. 0 to 4. |
| `vehicle.drive_side` | string | Steering wheel position: left for left-hand drive and right for right-hand drive. This is not the side of the road used by traffic. One of `left`, `right`. |
| `vehicle.flags` | object | Boolean risk and eligibility attributes. Only the documented keys have an effect: when one is true, the vehicle is outside the market's model and the valuation is refused with unsupported_vehicle (some keys only in the markets they name). false has the same effect as leaving the key out. Any other key is ignored with a flags_not_recognized warning, and a market-specific key sent for another market is ignored with a flags_not_applicable warning. At most 30 entries. |
| `vehicle.flags.is_damaged` | boolean | The vehicle is damaged. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.has_new_engine` | boolean | The engine has been replaced. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.is_leasing_price` | boolean | The price is a leasing price, not a sale price. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.has_no_battery` | boolean | An electric vehicle sold without its traction battery, for example under battery rental. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.is_auction_car` | boolean | The vehicle is sold at auction. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.is_commercial_car` | boolean | The vehicle is registered or sold as a commercial vehicle. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.price_is_leasing_rate` | boolean | The price is a periodic leasing rate, not a sale price. When true the vehicle is refused with unsupported_vehicle in every market. |
| `vehicle.flags.has_no_tax` | boolean | The price excludes registration tax. Applies in DK, SE, DE, ES, AT and PT, where true is refused with unsupported_vehicle. |
| `vehicle.flags.has_yellow_plates` | boolean | Registered on Danish yellow (commercial) plates. Applies in DK only, where true is refused with unsupported_vehicle. |
| `vehicle.flags.is_camper_version` | boolean | A camper conversion. Applies in DK only, where true is refused with unsupported_vehicle. |
| `vehicle.equipment` | array | Known equipment as feature keys from /v1/catalogue/enums, such as `EXTERIOR_TOWBAR_FIXED` or `INFOTAINMENT_NAVIGATION`, as strings or as the items of a returned Vehicle. The earlier keys such as `has_tow_bar` are still accepted. Unrecognized keys produce a warning. At most 150 items. |
| `vehicle.vin` | string | Optional vehicle identification number; the same as `registration.vin`. Live keys look it up: in DK in the Danish Motor Register, elsewhere with VIN decoding (make, model and model year). Never looked up in DE, IT or ES, or with test keys. Looked-up values only fill attributes you leave out and are identified against the catalogue like your own; their provenance in `identification.fields` has source registry and a source_id. A value that disagrees with one you supplied gives a registry_conflict warning while yours is used. If the lookup cannot be used, your other attributes are used and a warning says why. Included in the request's credit. The raw VIN is not retained. At most 30 characters. |
| `vehicle.registration_plate` | string | Optional registration plate; the same as `registration.registration_plate`. Live keys look it up in the national register where one is connected (DK, the Danish Motor Register); elsewhere it gives a registry_lookup_not_available warning, and a vin sent with it is still decoded. Looked-up values only fill attributes you leave out, as for vin. The odometer reading of the last inspection is never used as the mileage. Included in the request's credit. The raw plate is not retained. At most 30 characters. |
| `vehicle.identity` | object | Canonical identity: a catalogue ID per level, or a brand and model name. Canonical form of `make`, `model`, `variant` and `catalogue`. |
| `vehicle.identity.level` | string | Read-only part of a returned Vehicle. Accepted and ignored. |
| `vehicle.identity.<level>` | object | An identity level: `brand`, `model`, `generation`, `drivetrain` or `equipment_variant`. Send an `id`, or a `name` for `brand` and `model`. |
| `vehicle.identity.<level>.id` | string or null | Catalogue ID from the catalogue API or a returned Vehicle. Wins over `name`. All IDs must describe one consistent catalogue hierarchy. |
| `vehicle.identity.<level>.name` | string | Name as your source spells it. Used for `brand` and `model` when there is no `id`; ignored at the other levels. At most 200 characters. |
| `vehicle.identity.<level>.from_year` | integer | Read-only part of a returned generation. Ignored. |
| `vehicle.identity.<level>.to_year` | integer | Read-only part of a returned generation. Ignored. |
| `vehicle.identity.variant_text` | string | Free-text engine, trim or version designation; the same as `variant`. At most 200 characters. |
| `vehicle.specs` | object | Canonical technical facts: `energy.fuel` for `fuel`, `power.hp` or `power.kw` for `power_hp`, `transmission.type` for `transmission`, `traction` for `drive`, and `body`, `doors`, `seats`, `engine_size_l`, `battery_kwh` and `electric_range_km` as named. |
| `vehicle.specs.body` | string | Body type. One of `hatchback`, `estate`, `suv`, `sedan`, `mpv`, `convertible`, `coupe`. |
| `vehicle.specs.doors` | integer | Number of doors. 1 to 10. |
| `vehicle.specs.seats` | integer | Number of seats. 1 to 20. |
| `vehicle.specs.energy` | object | Energy source. |
| `vehicle.specs.energy.fuel` | string | Fuel or electrification type, from the public vocabulary of /v1/catalogue/enums. One of `petrol`, `diesel`, `electric`, `hybrid`, `plug_in_hybrid_petrol`, `plug_in_hybrid_diesel`, `lpg`, `cng`, `ethanol`, `hydrogen`. |
| `vehicle.specs.power` | object | Engine or drivetrain power. Returned in both units; on input `hp` wins over `kw`. |
| `vehicle.specs.power.hp` | number | Power in horsepower. 0 to 3000. |
| `vehicle.specs.power.kw` | number | Power in kilowatts, rounded. On input it is converted to horsepower (1 kW = 1.35962 hp) when `hp` is absent. 0 to 2300. |
| `vehicle.specs.engine_size_l` | number | Combustion engine displacement in litres, such as 1.5. 0 to 30. |
| `vehicle.specs.transmission` | object | Gearbox. Absent when unknown; absent does not mean manual. |
| `vehicle.specs.transmission.type` | string | Gearbox type. One of `manual`, `automatic`. |
| `vehicle.specs.traction` | string | Driven wheels. `2wd` means two-wheel drive with the driven axle not recorded, which is what the catalogue knows for most cars. One of `fwd`, `rwd`, `2wd`, `awd`, `4wd`. |
| `vehicle.specs.battery_kwh` | number | Traction battery capacity in kilowatt-hours. 0 to 500. |
| `vehicle.specs.electric_range_km` | number | Electric driving range in kilometres. 0 to 3000. |
| `vehicle.registration` | object | Canonical registration facts and identifiers. A VIN, plate or HSN/TSN pair is looked up as described for `vin`. |
| `vehicle.registration.country` | string | Read-only part of a returned Vehicle. Ignored: the request's `country` is the market. At most 10 characters. |
| `vehicle.registration.first_registration` | string (date) | First registration date (YYYY-MM-DD); the same as `first_registration`. At most 10 characters. |
| `vehicle.registration.model_year` | integer | Model or registration year; the same as `model_year`. 1900 to 2100. |
| `vehicle.registration.vin` | string | Vehicle identification number; the same as `vin`. At most 30 characters. |
| `vehicle.registration.registration_plate` | string | Registration plate; the same as `registration_plate`. At most 30 characters. |
| `vehicle.registration.hsn` | string | German manufacturer code (HSN, field 2.1 of the registration document). Looked up with `tsn` in the Kraftfahrt-Bundesamt type snapshot. At most 8 characters. |
| `vehicle.registration.tsn` | string | The first three characters of the German type code (TSN, field 2.2). Looked up with `hsn`. At most 8 characters. |
| `vehicle.registration.original_market` | string | The car's original sales market (ISO 3166-1 alpha-2), only when you know it independently. Used when a VIN is decoded. At most 10 characters. |
| `vehicle.registration.production_year` | integer | Read-only part of a returned Vehicle. Ignored. |
| `vehicle.listing` | object | Canonical facts about this particular car: `mileage`, `colour.name` for `color`, `condition.grade` for `condition`, `drive_side` and `flags`. |
| `vehicle.listing.mileage` | object | Odometer reading; the same as `mileage`. |
| `vehicle.listing.mileage.value` **required** | number | Non-negative odometer reading in the accompanying unit. 0 to 10000000. |
| `vehicle.listing.mileage.unit` **required** | string | Odometer unit: km, mi or mil (Scandinavian mile, 10 km). One of `km`, `mi`, `mil`. |
| `vehicle.listing.mileage.read_on` | string (date) | Read-only date of a register's reading. Ignored. A register's past inspection reading is not today's mileage: replace it before you value the car. |
| `vehicle.listing.colour` | object | Exterior colour. |
| `vehicle.listing.colour.name` **required** | string | Colour from your source; the same as `color`. At most 200 characters. |
| `vehicle.listing.colour.family` | string | Read-only part of a returned Vehicle. Accepted and ignored. At most 100 characters. |
| `vehicle.listing.condition` | object | Condition. |
| `vehicle.listing.condition.grade` **required** | number | Condition grade from 0 through 4; the same as `condition`. 0 to 4. |
| `vehicle.listing.drive_side` | string | Steering wheel position; the same as `drive_side`. One of `left`, `right`. |
| `vehicle.listing.flags` | object | Boolean risk and eligibility attributes; the same keys and effect as `flags`. At most 30 entries. |
| `vehicle.object` | string | Read-only part of a returned Vehicle. Accepted and ignored. |
| `vehicle.status` | string | Read-only part of a returned Vehicle. Accepted and ignored. |
| `vehicle.catalogue_version` | string | Read-only part of a returned Vehicle. Accepted and ignored. |
| `vehicle.fields` | object | Read-only part of a returned Vehicle. Accepted and ignored. |
| `vehicle.candidates` | object | Read-only part of a returned Vehicle. Accepted and ignored. |
| `description` | string | Unstructured listing text describing the vehicle. Existing parsers and deployment-configured optional AI can propose attributes; the response identifies assumptions and unresolved inputs. 1 to 20000 characters. |
| `images` | array | Up to eight vehicle photos, each supplied by HTTPS URL or inline base64 data. AI image resolution is deployment-configured and never runs for test keys. Warnings identify unused images. On a live key, photos cost one extra credit per request (not per photo), charged only when the request succeeds and a value was read from them (`usage.charges.images`); skipped or unused photos are not charged. At most 8 items. |
| `images[].url` | string (uri) | Public HTTPS image URL on port 443, without credentials or fragments. Private network destinations and redirects are rejected. Remote images must be supported image types and at most 8 MB each. At most 2048 characters. |
| `images[].data` | string | Strict base64-encoded image bytes, without a data-URL prefix. Inline data must also fit the total 1 MB API request limit. At most 1000000 characters. |
| `images[].media_type` | string | MIME type for inline image bytes: image/jpeg, image/png, image/webp or image/gif. The actual image signature is checked. At most 100 characters. |
| `pricing` | object | The asking-price context for this valuation. The result explicitly states its currency and whether the expected asking price is dealer retail or private sale. |
| `pricing.price_basis` | string | dealer_retail estimates a freshly listed dealer asking price; private_sale estimates a private seller asking price. These are not guaranteed transaction or trade-in prices. One of `dealer_retail`, `private_sale`. |
| `pricing.seller_region` | string | Known seller region within the selected market. This is passed as regional pricing context when available. At most 120 characters. |
| `pricing.asking_price` | number | Optional asking price in the market currency. Used to calculate AutoUncle price ratings and rating stability across the uncertainty interval. 0 to 100000000. |
| `options` | object | Resolution and minimum precision controls. Missing optional values use the documented default behaviour. |
| `options.resolution` | string | auto uses deterministic resolution and optional configured AI; no_ai uses deterministic resolution only; strict disables AI and refuses missing registration year or mileage. Mileage is never assumed without allow_mileage_estimation=true, and strict mode overrides that permission. Configured live AI is invoked only for missing identity/year or core drivetrain attributes, catalogue candidates the deterministic matcher cannot separate, equipment or condition the request does not supply, and whenever images are sent (for the equipment, colour, condition and drive side they show). An image that cannot be read is skipped with an image_skipped warning. Once invoked, a dependency timeout or outage fails the valuation; it is never silently treated as successful enrichment. One of `auto`, `no_ai`, `strict`. |
| `options.min_precision` | string | Minimum acceptable precision grade. If the result falls below this grade, the request is refused without consuming a credit. Sandbox results are indicative. One of `high`, `medium`, `low`, `indicative`. |
| `options.include` | array | Optional response sections to add. A section never changes the price, intervals or precision. `comparables` adds up to five comparable listings on sale and five recently sold in the same market, with top-level facts only, as supporting evidence for the valuation (see `comparables` in the response). One extra credit on a live key, charged only when listings are returned (`comparables.status` `included`) and released otherwise. Unavailable in Denmark, where the response says so with a note instead. `trade_in_price` adds AutoUncle's estimate of a fair trade-in price with a range (see `trade_in_price` in the response). One extra credit on a live key, charged only when it is returned (`trade_in_price.status` `included`). Available in AT, CH, DE, DK, ES, FR, GB, IT, NL, PL, PT and SE; in other markets the response says so with a note and nothing is charged. `similar_cars_link` adds `similar_cars_url`, a link to similar cars for sale on the market's AutoUncle site. Free, in every market. At most 10 items. |
| `options.allow_mileage_estimation` | boolean | Explicitly allow a fixed 96,000 km baseline when mileage cannot be extracted or supplied. This is an assumption, not a vehicle-specific estimate; it lowers precision. Default false. Strict resolution still refuses missing mileage. Default `false`. |
| `options.allow_equipment_estimation` | boolean | Explicitly allow equipment the request does not state to be assumed: the catalogue's equipment for the identified trim when the catalogue lists it, otherwise the equipment at least 70% of comparable vehicles on the market have. Assumed equipment is only added, never against equipment the request, its description or its photos state or deny, and is marked source imputed, basis assumed in identification.fields (availability unknown in vehicle.equipment), with an equipment_assumed warning and an improve_precision hint. Like any assumption it lowers precision to low. Test keys use only the catalogue trim, never market data. Default false. Strict resolution ignores it. Default `false`. |

## The valuation result

Returned by `POST /v1/valuations` (with `usage`), `GET /v1/valuations/{id}` (without `usage`), and the MCP `valuate_car` and `get_valuation` tools. When `status` is `valued`, the result contains `vehicle`, `identification`, `valuation`, `precision`, `price_ratings`, `improve_precision`, `warnings` and `model`. When it is `refused` or `failed`, it contains `error` instead and never `valuation`.

`vehicle` is the [Vehicle](/docs/reference/vehicles#the-vehicle-object) that was valued, an AVS vehicle document. [`identification`](/docs/reference/vehicles#identification) says how it was identified, lists competing catalogue records in `candidates` and where each value came from in `fields`. Results recorded before contract 0.9.0 are converted when you read them, so `GET /v1/valuations/{id}` returns the same shape for every result.

| Field | Type | Description |
| --- | --- | --- |
| `request_id` | string | Valuation ID (`val_…`, or `stf_…` for a selling-time forecast), also sent in the `X-Valuation-Id` response header. Use it with GET /v1/valuations/{id}, in the console request log and when you contact support. It is not the `X-Request-Id` header, which is the HTTP request ID. Pattern `^(val\|stf)_[A-Za-z0-9]+$`. |
| `object` | string | Always `valuation`. |
| `status` | string | `valued` when a price was produced, `refused` when the input cannot be valued as sent (fix the input), `failed` when a service failed (retry later). Only `valued` live results are billed. One of `valued`, `refused`, `failed`. |
| `country` | string | Valuation market as an ISO 3166-1 alpha-2 code, normalized from your request (for example `DK`). Pattern `^[A-Z]{2}$`. |
| `mode` | string | `test` for a test key (simulated result) or `live` for a live key. One of `live`, `test`. |
| `vehicle` | [Vehicle](/docs/reference/vehicles#the-vehicle-object) | The vehicle the valuation used, identified against the AutoUncle catalogue, as an AVS vehicle document; provenance per value is in `identification.fields`. Present when `status` is `valued` and the vehicle is identified to a brand and a model. |
| `identification` | [VehicleIdentification](/docs/reference/vehicles#identification) | How the vehicle was identified: status, depth, candidates and the provenance of every value in `vehicle`. |
| `valuation` | object | The estimate. Present only when `status` is `valued`. |
| `valuation.price` **required** | number | Point estimate in `currency`, for the stated `price_basis`. |
| `valuation.currency` **required** | string | ISO 4217 currency of the market, for example `DKK`, `SEK`, `EUR` or `GBP`. Pattern `^[A-Z]{3}$`. |
| `valuation.price_basis` **required** | string | `dealer_retail` or `private_sale`. Always read the price together with its basis. One of `dealer_retail`, `private_sale`. |
| `valuation.price_basis_description` **required** | string | Plain-language description of the price basis, suitable for display. |
| `valuation.intervals` **required** | array | Uncertainty intervals around the estimate, one per coverage level (currently 0.8, 0.95 and 0.99). |
| `valuation.intervals[].coverage` **required** | number | Intended share of comparable vehicles whose market price falls inside the interval, for example 0.8. |
| `valuation.intervals[].low` **required** | number | Lower bound in `currency`. |
| `valuation.intervals[].high` **required** | number | Upper bound in `currency`. |
| `valuation.intervals[].method` **required** | string | How the interval was produced. `calibrated` when it is calibrated against observed market outcomes, `estimated` otherwise; test results use `synthetic`. |
| `valuation.valuation_date` **required** | string (date) | Date the estimate applies to (YYYY-MM-DD). |
| `precision` | object | How much to rely on this result. See the precision guide. |
| `precision.grade` **required** | string | `high`, `medium`, `low` or `indicative`. Test results are always `indicative`. One of `high`, `medium`, `low`, `indicative`. |
| `precision.summary` **required** | string | Plain-language summary of the grade, suitable for display. |
| `precision.identity_level` **required** | string | Most specific catalogue level that was resolved, for example `generation` or `drivetrain`. |
| `precision.interval_width_pct` **required** | number or null | Width of the 80% interval as a percentage of the price, or null. Minimum 0. |
| `precision.data_support` **required** | object | How much comparable market data stands behind the estimate. `comparable_vehicles` is a lower bound (0, 10, 30, 100, 300, 1000, 3000 or 10000), not an exact count. Empty for test results. |
| `precision.typical_error_pct` **required** | number or null | Typical error of comparable estimates as a percentage, or null when not available. Minimum 0. |
| `price_ratings` | object | AutoUncle's five price-rating bands for this vehicle, and the rating of your asking price. |
| `price_ratings.bands` **required** | array | Exactly five bands, from rating 5 (Super price) to 1 (Expensive). At most 5 items. |
| `price_ratings.bands[].rating` **required** | integer | Rating from 5 (best price for a buyer) to 1. 1 to 5. |
| `price_ratings.bands[].label` **required** | string | Display label, for example `Good price`. |
| `price_ratings.bands[].from` **required** | number | Lower price bound of the band in `currency`. Minimum 0. |
| `price_ratings.bands[].to` **required** | number | Upper price bound of the band in `currency`. Minimum 0. |
| `price_ratings.asking_price_rating` **required** | integer or null | Rating of `pricing.asking_price` from 1 to 5, or null when you did not send an asking price. 0 to 5. |
| `price_ratings.asking_price_label` **required** | string or null | Label of that rating, or null. |
| `price_ratings.stable_within_80pct_interval` **required** | boolean or null | `true` when the asking-price rating stays the same anywhere in the 80% interval, `false` when it could change; null without an asking price. |
| `comparables` | object | Comparable listings in the valuation market, as supporting evidence. Present on a `valued` result when `options.include` contains `comparables`. They are looked up after scoring and never change the valuation. At most five on sale and five recently sold, with top-level facts only; no seller details, listing text, plates, VINs, images, dates or links. |
| `comparables.status` **required** | string | `included` when at least one listing is returned, `none_found` when no listing matched the criteria, `unavailable` when comparables cannot be provided (see `unavailable_reason`). One of `included`, `none_found`, `unavailable`. |
| `comparables.unavailable_reason` **required** | string or null | `market_restricted` when the market's listing-data agreements do not allow passing listings on (Denmark; a `comparables_unavailable_in_market` note says so), `temporarily_unavailable` when the lookup failed or ran out of time (with a `comparables_unavailable` warning; request again). Null otherwise. One of `market_restricted`, `temporarily_unavailable`. |
| `comparables.synthetic` **required** | boolean | `true` for test keys: fixed examples around the simulated price, not market listings. |
| `comparables.criteria` **required** | object or null | What every listing had to match. Null when `status` is `unavailable`. |
| `comparables.criteria.make` **required** | string | Make of the valued vehicle. |
| `comparables.criteria.model` **required** | string | Model of the valued vehicle. |
| `comparables.criteria.model_year` **required** | object or null | Model year range, inclusive. |
| `comparables.criteria.model_year.from` **required** | integer or null | Earliest model year. |
| `comparables.criteria.model_year.to` **required** | integer or null | Latest model year. |
| `comparables.criteria.mileage` **required** | object or null | Mileage range, inclusive, or null when mileage was not limited. |
| `comparables.criteria.mileage.from` **required** | integer or null | Lowest mileage. |
| `comparables.criteria.mileage.to` **required** | integer or null | Highest mileage. |
| `comparables.criteria.mileage.unit` **required** | string | The market's mileage unit. One of `km`, `mi`, `mil`. |
| `comparables.criteria.fuel` **required** | string or null | Required fuel, or null when not limited. One of `petrol`, `diesel`, `electric`, `hybrid`, `plug_in_hybrid_petrol`, `plug_in_hybrid_diesel`, `lpg`, `cng`, `ethanol`, `hydrogen`. |
| `comparables.criteria.transmission` **required** | string or null | Required transmission, or null when not limited. Only a known automatic or manual gearbox limits it. One of `manual`, `automatic`. |
| `comparables.criteria.body` **required** | string or null | Required body type, or null when not limited. One of `hatchback`, `estate`, `suv`, `sedan`, `mpv`, `convertible`, `coupe`. |
| `comparables.criteria.engine_size_l` **required** | number or null | Required engine displacement in litres, or null when not limited. |
| `comparables.criteria.sold_within_days` **required** | integer | How recently a `recently_sold` listing left the market, in days. Minimum 1. |
| `comparables.on_sale` **required** | [ComparableListing](/docs/reference/valuations#comparable-listings) array | Up to five listings on sale now, most typical price rating first, then nearest model year and mileage. At most 5 items. |
| `comparables.recently_sold` **required** | [ComparableListing](/docs/reference/valuations#comparable-listings) array | Up to five listings that left the market within `criteria.sold_within_days`, in the same order. AutoUncle treats a listing that left the market as sold; its price is the last asking price. At most 5 items. |
| `trade_in_price` | object | AutoUncle's estimate of a fair price for a dealer to pay when taking the vehicle in trade, with a range. Present on a `valued` result when `options.include` contains `trade_in_price`. It is an estimate, not an offer, and it relates to the vehicle's dealer retail market value whatever `pricing.price_basis` the valuation uses. Looked up after scoring; it never changes the valuation. |
| `trade_in_price.status` **required** | string | `included` when a trade-in price is returned, `unavailable` when it cannot be provided (see `unavailable_reason`). One of `included`, `unavailable`. |
| `trade_in_price.unavailable_reason` **required** | string or null | `market_unsupported` in a market without trade-in prices (any market outside AT, CH, DE, DK, ES, FR, GB, IT, NL, PL, PT and SE, such as FI, RO and BE; a `trade_in_price_unavailable_in_market` note says so), `temporarily_unavailable` when it could not be calculated for this request (with a `trade_in_price_unavailable` warning; request again). Null otherwise. One of `market_unsupported`, `temporarily_unavailable`. |
| `trade_in_price.synthetic` **required** | boolean | `true` for test keys: a fixed example derived from the simulated price, not a trade-in estimate. |
| `trade_in_price.price` **required** | integer or null | Estimated fair trade-in price in `currency`, rounded. Null when `status` is `unavailable`. |
| `trade_in_price.low` **required** | integer or null | Lower end of the trade-in range in `currency`. Null when `status` is `unavailable`. |
| `trade_in_price.high` **required** | integer or null | Upper end of the trade-in range in `currency`. Null when `status` is `unavailable`. |
| `trade_in_price.currency` **required** | string | ISO 4217 currency of the market. Pattern `^[A-Z]{3}$`. |
| `similar_cars_url` | string or null (uri) | Link to cars similar to the valued vehicle for sale on the market's own AutoUncle site (autouncle.<country domain>), in the market's language. Present on a `valued` result when `options.include` contains `similar_cars_link`; null when the link could not be built (a `similar_cars_link_unavailable` warning says so). Free. |
| `selling_time` | object | The selling-time forecast. Present only on `valued` results of POST /v1/selling-times: how long the vehicle is expected to take to sell if listed now and its asking price is kept. See [selling-time forecasts](/docs/selling-time). |
| `improve_precision` | array | Specific inputs that would make the result more precise, most useful first. |
| `improve_precision[].field` **required** | string | Request field to supply, for example `vehicle.catalogue.drivetrain_id` or `vehicle.condition`. |
| `improve_precision[].reason` **required** | string | Machine-readable reason, for example `drivetrain_unresolved`, `condition_unknown`, `imputed` or `ai_interpreted`. |
| `improve_precision[].expected_impact` **required** | string | `high`, `medium` or `low`: qualitative, not a promise that the price or interval will change by a fixed amount. One of `high`, `medium`, `low`. |
| `improve_precision[].message` **required** | string | Plain-language hint, suitable for display. |
| `improve_precision[].candidates` | array | Catalogue candidates to choose from, when the hint is about an ambiguous identity. |
| `improve_precision[].candidates[].id` **required** | string | Catalogue ID of the candidate. |
| `improve_precision[].candidates[].name` **required** | string | Catalogue name of the candidate. |
| `improve_precision[].candidates[].source` **required** | string | How the candidate was found. One of `provided`, `catalogue_id`, `catalogue_derived`, `text_parser`, `registry`, `catalogue_match`, `ai_text`, `ai_vision`, `imputed`, `default`. |
| `improve_precision[].candidates[].basis` | string | How the value was established: observed (supplied by the caller or read from a registry record), extracted (parsed or automatically interpreted from supplied text or photos), catalogue (deterministically derived from or matched against the AutoUncle catalogue) or assumed (a heuristic default or fixed baseline, not evidence about this vehicle). One of `observed`, `extracted`, `catalogue`, `assumed`. |
| `improve_precision[].candidates[].match_score` | number | Match strength from 0 to 1. |
| `improve_precision[].candidates[].ambiguous` | boolean | Whether the candidate itself is ambiguous. |
| `improve_precision[].candidates[].candidate_count` | integer | Number of fitting entries when ambiguous. Minimum 2. |
| `warnings` | array | Problems with this request's input or its optional sections, for example `generation_ambiguous`, `equipment_not_recognized`, `flags_not_recognized`, `flags_not_applicable`, `images_not_used`, `km_imputed`, `registry_conflict`, `vehicle_input_overridden`, `comparables_unavailable`, `trade_in_price_unavailable` or `similar_cars_link_unavailable`. Match on `code`. |
| `warnings[].code` **required** | string | Stable machine-readable warning code. Pattern `^[a-z][a-z0-9_]*$`. |
| `warnings[].message` **required** | string | Plain-language explanation. |
| `model` | object | The public identity of the model that produced the result. Present when the request was scored. |
| `model.model_id` **required** | string | Opaque identifier of the model release, stable for one release and different for the next (for example `dk-3f9a1c0b7e2d`). Test results use `sandbox-v1`. |
| `model.trained_on` **required** | string or null (date-time) | When the model was trained (ISO 8601), or null. |
| `model.catalogue_version` **required** | string or null | Catalogue version the model was built against, or null. |
| `model.synthetic` **required** | boolean | `true` for simulated test-mode results. |
| `usage` | object | Billing for this call. Present on POST responses; GET read-backs omit it. |
| `usage.billable` **required** | boolean | `true` when this valuation captured a credit. |
| `usage.credits_used` **required** | integer | Credits this call consumed. Always 0 on an idempotent replay. 0 to 4. |
| `usage.original_credits_used` **required** | integer | Credits the original valuation consumed (0, 1, or more with add-ons for comparables, a trade-in price, photos or a selling-time forecast), also on a replay. 0 to 4. |
| `usage.charges` **required** | object | What `original_credits_used` paid for. Empty when nothing was charged (test keys, refused and failed valuations). |
| `usage.charges.base` | integer | The valuation itself, 1 credit. Minimum 1. |
| `usage.charges.comparables` | integer | Comparable listings, 1 credit. Only when they were requested and returned with `comparables.status` `included`. Minimum 1. |
| `usage.charges.images` | integer | Image processing, 1 credit per request. Only when photos were sent and a value in `identification.fields` was read from them. Minimum 1. |
| `usage.charges.selling_time` | integer | The selling-time forecast of POST /v1/selling-times, 1 credit. Only on a `valued` result, which always carries the forecast. Minimum 1. |
| `usage.charges.trade_in_price` | integer | Trade-in price, 1 credit. Only when it was requested and returned with `trade_in_price.status` `included`. Minimum 1. |
| `usage.credits_remaining` **required** | integer | Workspace credits left after this call. Minimum 0. |
| `usage.cache_hit` **required** | boolean | Reserved. Always false in this version. |
| `usage.idempotent_replay` **required** | boolean | `true` when this response replays an earlier recorded outcome for the same Idempotency-Key and body. |
| `usage.mode` **required** | string | `test` or `live`. One of `live`, `test`. |
| `error` | [Problem](/docs/reference/valuations#the-problem-object) | The error for a `refused` or `failed` valuation, in the same Problem format as request errors. |
| `notes` | [Note](/docs/notices#notes) array | Standing limitations, disclaimers and legal notices. Always present. |
| `attributions` | [Attribution](/docs/notices#attributions) array | Data sources that contributed to this result. Always present. |

### A complete test-mode result

```json
{
  "request_id": "val_05f96b492a25a0ef9eb7aa99218a43be",
  "object": "valuation",
  "country": "DK",
  "mode": "test",
  "status": "valued",
  "vehicle": {
    "avs": { "version": "0.3", "kind": "vehicle" },
    "identity": {
      "brand": { "name": "VW", "ids": [{ "scheme": "autouncle", "value": "b-0957579dc5bca6de229d2f32" }] },
      "model": { "name": "Golf VII", "ids": [{ "scheme": "autouncle", "value": "cm-88dbede1978bc412872a6e1c" }] }
    },
    "vehicle": {
      "registration": { "country": "DK", "modelYear": 2020 },
      "odometer": { "km": 60000 }
    }
  },
  "identification": {
    "status": "ambiguous",
    "level": "model",
    "catalogue_version": "5.6.9:NEW",
    "candidates": {
      "generation": [
        { "id": "mg-43ed101760c6bc4c4c2e44bd", "name": "Golf VII (5-door, facelift 2017)", "from_year": 2017, "to_year": 2021, "score": 0.999999 },
        { "id": "mg-5b0e2f6c8d1a4e7b9c3f2a10", "name": "Golf VII Variant (facelift 2017)", "from_year": 2017, "to_year": 2021, "score": 0.999999 }
      ]
    },
    "fields": {
      "/identity/body": { "basis": "catalogue", "source": "catalogue_match", "status": "ambiguous", "candidate_count": 2 },
      "/identity/brand": { "basis": "catalogue", "source": "catalogue_match", "status": "derived", "match_score": 1.0 },
      "/identity/model": { "basis": "catalogue", "source": "catalogue_match", "status": "derived", "match_score": 1.0 },
      "/vehicle/odometer": { "basis": "observed", "source": "provided", "status": "supplied" },
      "/vehicle/registration/modelYear": { "basis": "observed", "source": "provided", "status": "supplied" }
    }
  },
  "valuation": {
    "price": 102673,
    "currency": "DKK",
    "price_basis": "dealer_retail",
    "price_basis_description": "Expected asking price when freshly listed by a dealer.",
    "intervals": [
      { "coverage": 0.8, "low": 82138, "high": 123208, "method": "synthetic" },
      { "coverage": 0.95, "low": 66737, "high": 138609, "method": "synthetic" },
      { "coverage": 0.99, "low": 51337, "high": 154010, "method": "synthetic" }
    ],
    "valuation_date": "2026-10-26"
  },
  "precision": {
    "grade": "indicative",
    "summary": "Synthetic sandbox result. Not a market valuation.",
    "identity_level": "car_model",
    "interval_width_pct": 40.0,
    "data_support": {},
    "typical_error_pct": null
  },
  "price_ratings": {
    "bands": [
      { "rating": 5, "label": "Super price", "from": 69588, "to": 86130 },
      { "rating": 4, "label": "Good price", "from": 86130, "to": 94402 },
      { "rating": 3, "label": "Fair price", "from": 94402, "to": 110944 },
      { "rating": 2, "label": "A bit expensive", "from": 110944, "to": 119216 },
      { "rating": 1, "label": "Expensive", "from": 119216, "to": 135758 }
    ],
    "asking_price_rating": null,
    "asking_price_label": null,
    "stable_within_80pct_interval": null
  },
  "improve_precision": [
    { "field": "vehicle.catalogue.drivetrain_id", "reason": "drivetrain_unresolved", "expected_impact": "high", "message": "Select the exact engine and transmission from the catalogue." },
    { "field": "vehicle.condition", "reason": "condition_unknown", "expected_impact": "medium", "message": "Provide the vehicle's condition." }
  ],
  "warnings": [
    { "code": "generation_ambiguous", "message": "More than one generation fits the supplied information. Select its catalogue ID for greater precision." }
  ],
  "model": { "model_id": "sandbox-v1", "trained_on": null, "catalogue_version": "NEW", "synthetic": true },
  "notes": [
    { "code": "estimate_not_offer", "category": "disclaimer", "message": "This is a statistical estimate for the stated price basis. It is not an offer, an appraisal or a guaranteed transaction price.", "pointers": ["/valuation"], "source_ids": [] },
    { "code": "market_specific", "category": "limitation", "message": "This result applies only to the DK market, its currency and the stated price basis. Do not apply it to another market.", "pointers": ["/valuation", "/price_ratings"], "source_ids": [] },
    { "code": "synthetic_result", "category": "limitation", "message": "Synthetic sandbox result from a deterministic simulator. No market data or production valuation model contributed. Do not use it as a market valuation.", "pointers": ["/valuation", "/precision", "/price_ratings"], "source_ids": [] }
  ],
  "attributions": [
    {
      "source_id": "autouncle_vehicle_catalogue",
      "name": "AutoUncle vehicle catalogue",
      "url": "https://data-services.autouncle.com/docs/catalogue",
      "party": "first_party",
      "role": "vehicle_catalogue",
      "license": { "id": "autouncle_data_services_terms", "name": "AutoUncle Data Services terms", "url": "https://data-services.autouncle.com/legal/terms" },
      "attribution_text": null,
      "notice_status": "pending_review",
      "notice_version": "autouncle_vehicle_catalogue@1",
      "pointers": ["/vehicle/identity/brand", "/vehicle/identity/model"]
    }
  ],
  "usage": { "billable": false, "credits_used": 0, "original_credits_used": 0, "charges": {}, "credits_remaining": 0, "cache_hit": false, "idempotent_replay": false, "mode": "test" }
}
```

### Comparable listings

With `"options": { "include": ["comparables"] }`, a `valued` result also has `comparables`: up to five similar listings on sale and five recently sold in the same market, with top-level facts only, as evidence beside the price. Each listing is a ComparableListing. They cost one extra credit on a live key, charged only when listings are returned, and never change the valuation. See [comparable listings](/docs/valuations#comparable-listings) for how they are selected and how to show them.

| Field | Type | Description |
| --- | --- | --- |
| `make` | string | Make as listed. |
| `model` | string | Model as listed. |
| `model_year` | integer or null | Model year (registration year), or null. |
| `mileage` | object or null | Odometer reading, rounded, in the market's unit, or null when the listing gives none. |
| `mileage.value` **required** | number | Mileage rounded to the nearest 5,000 km or mi, or the nearest 500 Scandinavian mil. Minimum 0. |
| `mileage.unit` **required** | string | `km`, `mi` or `mil`. One of `km`, `mi`, `mil`. |
| `asking_price` | integer | Asking price in `currency`, rounded to three significant figures (12,345 becomes 12,300). For a recently sold listing, the last asking price, not the transaction price. Leasing rates are never included. |
| `currency` | string | ISO 4217 currency of the market. Pattern `^[A-Z]{3}$`. |
| `price_rating` | integer or null | AutoUncle price rating of the listing from 1 (Expensive) to 5 (Super price), or null when it was not rated. 1 to 5. |
| `days_on_market` | integer or null | Days the listing has been for sale, or was for sale until it left the market. Minimum 0. |

```json
{
  "comparables": {
    "status": "included",
    "unavailable_reason": null,
    "synthetic": false,
    "criteria": {
      "make": "Volvo", "model": "XC60",
      "model_year": { "from": 2020, "to": 2022 },
      "mileage": null,
      "fuel": "plug_in_hybrid_petrol", "transmission": "automatic", "body": "suv", "engine_size_l": 2.0,
      "sold_within_days": 30
    },
    "on_sale": [
      {
        "make": "Volvo", "model": "XC60", "model_year": 2021,
        "mileage": { "value": 7000, "unit": "mil" },
        "asking_price": 430000, "currency": "SEK", "price_rating": 3,
        "days_on_market": 18
      }
    ],
    "recently_sold": [
      {
        "make": "Volvo", "model": "XC60", "model_year": 2021,
        "mileage": { "value": 6000, "unit": "mil" },
        "asking_price": 439000, "currency": "SEK", "price_rating": 3,
        "days_on_market": 47
      }
    ]
  }
}
```

In Denmark `status` is `unavailable` with `unavailable_reason: "market_restricted"`, empty lists and a `comparables_unavailable_in_market` note.

### Trade-in price and link to similar cars

With `"options": { "include": ["trade_in_price", "similar_cars_link"] }`, a `valued` result also has `trade_in_price`, AutoUncle's estimate of a fair trade-in price with a range, and `similar_cars_url`, a link to similar cars for sale on the market's AutoUncle site. The trade-in price costs one extra credit on a live key, charged only when it is returned; the link is free. Neither changes the valuation. See [trade-in price](/docs/valuations#trade-in-price) and [link to similar cars](/docs/valuations#link-to-similar-cars).

```json
{
  "trade_in_price": {
    "status": "included",
    "unavailable_reason": null,
    "synthetic": false,
    "price": 17800,
    "low": 17400,
    "high": 18200,
    "currency": "EUR"
  },
  "similar_cars_url": "https://www.autouncle.de/de/gebrauchtwagen/VW/Golf%20VIII/f-benzin/y-2021/b-hatchback?…"
}
```

In every other market, such as Finland, Romania and Belgium, `trade_in_price.status` is `unavailable` with `unavailable_reason: "market_unsupported"`, null prices and a `trade_in_price_unavailable_in_market` note.

### A refused result

A refusal is recorded, free and replayable. It uses the error's HTTP status (here `422`) and the same envelope:

```json
{
  "request_id": "val_ff744d44049c52dd6cb9d22b13e45636",
  "object": "valuation",
  "country": "DK",
  "mode": "test",
  "status": "refused",
  "error": {
    "type": "https://data-services.autouncle.com/docs/errors#missing_mileage",
    "title": "Missing mileage",
    "status": 422,
    "code": "missing_mileage",
    "detail": "Supply the actual mileage in vehicle.mileage, or explicitly set options.allow_mileage_estimation to true to use a fixed 96,000 km baseline assumption.",
    "errors": [{ "pointer": "/vehicle/mileage", "message": "Actual mileage or explicit baseline permission is required." }],
    "fix": [
      "Supply vehicle.mileage with its value and unit.",
      "If a fixed baseline assumption is acceptable, set options.allow_mileage_estimation to true. Strict resolution still requires actual mileage."
    ],
    "request_id": "val_ff744d44049c52dd6cb9d22b13e45636",
    "docs_url": "https://data-services.autouncle.com/docs/errors",
    "billable": false,
    "retryable": false
  },
  "notes": [],
  "attributions": [],
  "usage": { "billable": false, "credits_used": 0, "original_credits_used": 0, "charges": {}, "credits_remaining": 0, "cache_hit": false, "idempotent_replay": false, "mode": "test" }
}
```

## The Problem object

Errors that stop a request before a valuation is recorded (authentication, validation, limits) return a Problem document with `Content-Type: application/problem+json`. Refused and failed valuations carry the same object in `error`. See [errors & retries](/docs/errors) for every code.

| Field | Type | Description |
| --- | --- | --- |
| `type` | string | URL of this error code's entry in the error reference. At most 200 characters. |
| `title` | string | Short human-readable title derived from the code. At most 200 characters. |
| `status` | integer | HTTP status code. |
| `code` | string | Stable machine-readable error code. Match on this, never on `detail`. At most 200 characters. |
| `detail` | string | Human-readable explanation. Wording can change; do not parse it. At most 2000 characters. |
| `request_id` | string or null | Request ID to share with support. A `val_…` ID when a valuation was recorded, otherwise the HTTP request ID. |
| `billable` | falseclass | Always false. Errors never consume credits. |
| `errors` | array | Affected request fields, when known. |
| `errors[].pointer` **required** | string | JSON Pointer (RFC 6901) into your request, for example `/vehicle/mileage/value`. |
| `errors[].message` **required** | string | What is wrong with that field. |
| `fix` | array | Actionable recovery steps, including replay guidance when relevant. |
| `docs_url` | string | Link to the error reference. At most 200 characters. |
| `retryable` | boolean | Whether retrying after the documented recovery steps may succeed. Follow fix for waiting, input changes and idempotency-key/replay semantics. |
| `service` | string | Safe public service identifier, never a private hostname or provider response. |
| `reason` | string | Safe enumerated domain refusal reason when known. |
| `retry_after` | integer | Seconds to wait before retrying, when known. Equals the Retry-After header on REST and is the only retry delay over MCP, which has no response headers. Minimum 1. |

`service` (the public name of a failing dependency, such as `valuation_engine` or `image_fetch`), `reason` (a refusal reason, when known) and `retry_after` (seconds to wait) appear only when they apply.