---
title: "Top offers"
description: "Live auctions our pipeline judged to be priced below their market reference. Same deals as /api/search?sort=top_offers, but each card additionally carries the reference the verdict was made against."
canonical: "https://thecarapi.com/docs/top-offers"
contract_version: "2026-08-19"
api_base: "https://api.thecarapi.com"
source: "https://thecarapi.com/docs/top-offers.md"
---

# Top offers

Live auctions our pipeline judged to be priced below their market reference. Same deals as /api/search?sort=top_offers, but each card additionally carries the reference the verdict was made against.

## GET /api/top-offers

Feed of auctions priced below their market reference, newest comparison first.

**Scope:** `top-offers`

### Parameters

| Parameter | Send in | Type | Required | Example | Where the value comes from | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `site` | Query string | string | no | `ecarstrade` | /api/sites -> sites[].name | Comma-separated source slugs. An unknown value returns 400. |
| `site_exclude` | Query string | string | no | `copart` | /api/sites -> sites[].name | Comma-separated source slugs to leave out. Same rules as on /api/search. |
| `steering` | Query string | enum | no | `left` | left \| lhd \| right \| rhd — any other value is a 400. | Left- or right-hand drive. |
| `brand` | Query string | string | no | `BMW` | /api/search -> results[].clean_make | Exact clean_make, case-insensitive. |
| `model` | Query string | string | no | `3 Series` | /api/search -> results[].clean_model | Exact clean_model, case-insensitive. |
| `country` | Query string | string | no | `DE` | /api/countries -> country_details[].code | Vehicle country code, case-insensitive. |
| `year_from / year_to` | Query string | integer | no | `2018 / 2024` | Year bounds chosen by your user. | First-registration year bounds. |
| `kilometers_from / kilometers_to` | Query string | integer | no | `0 / 150000` | Mileage bounds chosen by your user. | Mileage bounds. |
| `price_from / price_to` | Query string | integer | no | `5000 / 25000` | EUR budget chosen by your user. | Public EUR price bounds. |
| `min_savings_pct` | Query string | integer | no | `20` | Threshold chosen by your application. | Only offers saving at least this percentage. |
| `sort` | Query string | enum | no | `savings_pct` | Choose savings_pct, savings, price_low, price_high, or newest. | Default savings_pct. |
| `limit / offset` | Query string | integer | no | `24 / 0` | Pagination state in your application. | Or page_size / page. limit caps at 100. |

### Example requests

```http
GET https://api.thecarapi.com/api/top-offers?site=openlane&min_savings_pct=20&limit=24
```

```http
GET https://api.thecarapi.com/api/top-offers?brand=BMW&country=DE&sort=savings&page=2&page_size=20
```

### Example response

```json
{
  "success": true,
  "results": [
    {
      "auction_id": 8842711,
      "site_name": "openlane",
      "car_name_en": "BMW 320d Touring",
      "clean_make": "BMW",
      "clean_model": "3 Series",
      "public_price_eur": 9000,
      "is_top_offer": true,
      "top_offer_savings": 2500,
      "top_offer_savings_pct": 21.7,
      "market_reference": {
        "price_eur": 11500,
        "mileage": 165000,
        "km_difference": -15000,
        "explanation": "Rule: this car must save at least 1,800 EUR — ..."
      }
    }
  ],
  "total": 318,
  "limit": 24,
  "offset": 0,
  "total_pages": 14
}
```

### Response fields

| Field | Type | Meaning |
| --- | --- | --- |
| `results[]` | object[] | A standard search result card — every field documented in the data dictionary — plus the top-offer fields below. |
| `is_top_offer` | boolean | Always true on this feed. Also present on /api/search cards. |
| `top_offer_savings` | number | Absolute EUR saving against the market reference. |
| `top_offer_savings_pct` | number | Saving as a percentage of the reference price. Default sort key. |
| `market_reference.price_eur` | number | The reference price this car was measured against. |
| `market_reference.mileage` | integer | The reference mileage, so you can judge whether the comparison is like-for-like. |
| `market_reference.km_difference` | integer | This car’s mileage minus the reference. Negative means this car has done fewer kilometres. |
| `market_reference.explanation` | string | The rule that admitted this car to the feed, in words — e.g. the minimum EUR saving it had to clear. |

**Notes.** A car qualifies only when its saving clears a continuous, reference-quality-aware bar — wider price spread, thinner evidence, and slower-selling models all raise it — so this is a shortlist, not everything below average. Rows leave the feed the moment the auction ends, so total shrinks through the day and grows again after each comparison run. The comparable’s own listing URL and identity are not exposed. A non-numeric value on a numeric parameter is a 400, not a dropped filter.