Endpoints

Historical inventory

Ended listings moved into the archive, separate from ended rows still in the live table. Requires the archive scope. A last observed price is not a confirmed sale price.

GET

/api/archive/search

Search ended auctions

Requires the archive scope.

Parameters

sitestring · query string

Comma-separated source slugs from `/api/sites`, OR within the parameter. Case-insensitive; padding and empty members are ignored. An unknown slug is a `400` naming the offender.

Example openlane,ecarstrade·Where the value comes from Current API reference

site_excludestring · query string

Comma-separated source slugs to leave out. Same rules as `site`.

Example copart·Where the value comes from Current API reference

brandstring · query string

Brand display name, slug (from `/api/brands`), or numeric `brand_id`.

Example bmw·Where the value comes from Current API reference

modelstring · query string

Model name or slug.

Example 320d·Where the value comes from Current API reference

countrystring · query string

ISO country code from `/api/countries`, or the pseudo-country `europe`. Accepted and ignored by `/api/sites` and `/load-models`.

Example DE·Where the value comes from Current API reference

fuelstring · query string

Canonical fuel group from `/api/fuels`.

Example Diesel·Where the value comes from Current API reference

gearboxstring · query string

Canonical gearbox group from `/api/gearboxes`.

Example Automatic·Where the value comes from Current API reference

year_frominteger · query string

Lower bound on registration year, inclusive.

Example 2018·Where the value comes from Current API reference

year_tointeger · query string

Upper bound on registration year, inclusive.

Example 2024·Where the value comes from Current API reference

production_year_frominteger · query string

Lower bound on production year, inclusive. `production_year` falls back to the registration year where the source publishes no build year, so missing build-year evidence falls back to the registration-year dimension.

Example 2018·Where the value comes from Current API reference

production_year_tointeger · query string

Upper bound on production year, inclusive.

Example 2024·Where the value comes from Current API reference

kilometers_frominteger · query string

Lower bound on mileage in kilometres.

Example 0·Where the value comes from Current API reference

kilometers_tointeger · query string

Upper bound on mileage in kilometres.

Example 150000·Where the value comes from Current API reference

price_frominteger · query string

Lower bound on the public EUR price.

Example 1000·Where the value comes from Current API reference

price_tointeger · query string

Upper bound on the public EUR price.

Example 30000·Where the value comes from Current API reference

archived_fromstring · query string

Only lots archived on or after this date (`YYYY-MM-DD`). Anything else is a `400`.

Example 2026-07-01·Where the value comes from Current API reference

archived_tostring · query string

Only lots archived on or before this date (`YYYY-MM-DD`). Inclusive of the whole day named.

Example 2026-08-31·Where the value comes from Current API reference

vinstring · query string

Exact full-VIN filter. Punctuation and case are ignored. A value that is not a valid 17-character VIN is a `400`. VIN coverage varies; query /api/archive/stats before relying on it.

Example WBA8E9G50GNU12345·Where the value comes from Current API reference

sortstring · query string

Result ordering.

Example archived_desc·Where the value comes from Current API reference

limitinteger · query string

Page size. Capped at `pagination.max_limit` from `GET /api/contract` (100 by default); larger values are clamped down rather than rejected. Do not combine with `page_size` — that is a `400`.

Example 20·Where the value comes from Current API reference

offsetinteger · query string

0-based row offset. Do not combine with `page` — that is a `400`. Bounded by `pagination.max_offset` (5000 by default) on archive, catalog, top-offers and classifieds; /api/search and /api/listVehicles have no offset cap.

Example 0·Where the value comes from Current API reference

pageinteger · query string

1-based page number; maps to `offset = (page - 1) * limit`. Do not combine with `offset`.

Example 1·Where the value comes from Current API reference

page_sizeinteger · query string

Alias for `limit`. Do not combine with `limit`.

Example 20·Where the value comes from Current API reference

include_totalboolean · query string

`false` returns `total: null` and skips the count, which is faster.

Example true·Where the value comes from Current API reference

Example requests

Request

GET https://api.thecarapi.com/api/archive/search?site=japan&year_from=2020&limit=20

GET https://api.thecarapi.com/api/archive/search?brand=bmw&archived_from=2026-09-01

Example response

json

{
  "success": true,
  "results": [],
  "total": 0,
  "limit": 20,
  "offset": 0,
  "sort": "archived_desc",
  "page": 1,
  "page_size": 20,
  "total_pages": 0,
  "max_page": 0,
  "contract_version": "2026-09-03"
}

Notes

The historical counterpart to `/api/search`. It reads `auctions_archive`, which holds lots that ended, stayed inactive for the retention window, and were moved out of the live table with an `archived_at` stamp. Nothing here is buyable. **This is not a sold-price index.** `public_price_eur` is the last public price observed. `final_price` may be absent or have an unverified result basis; it is not proof of a completed sale. Call `/api/archive/stats` for the per-source coverage before building anything on a particular field. **No free-text `search` parameter.** The archive carries no trigram index, and a substring scan across it costs seconds. `brand` and `model` match exactly (case- and slug-insensitive), as they do on `/api/search`. Default ordering is newest-archived first. The general offset cap (`pagination.max_offset`, 5000 by default) applies — there is no unfiltered deep-paging path here.

GET

/api/archive/auction/{site_slug}/{auction_id}

One archived auction in full

Requires the archive scope.

Parameters

site_slugstring · in the URL pathrequired

Example openlane·Where the value comes from Current API reference

auction_idinteger · in the URL pathrequired

The source's auction id, as published on the search card.

Example 38112900·Where the value comes from Current API reference

Example request

Request

GET https://api.thecarapi.com/api/archive/auction/encar/38112900

Example response

json

{
  "success": true,
  "auction": {
    "site_name": "encar",
    "auction_id": 38112900,
    "auction_id_str": "38112900",
    "archived": true,
    "archived_at": "2026-09-01T12:00:00",
    "final_price": null
  },
  "contract_version": "2026-09-03"
}

GET

/api/archive/stats

Archive coverage per source

Requires the archive scope.

Example request

Request

GET https://api.thecarapi.com/api/archive/stats

Example response

json

{
  "success": true,
  "total": 0,
  "archived_from": null,
  "archived_to": null,
  "sources": [],
  "contract_version": "2026-09-03"
}