Get Auctions#

Retrieve paginated auction listings with filtering and sorting options. Starter plan users are limited to the latest 20 auctions.

GEThttps://api.oldcarsdata.com/auctions

GET/auctions?make=Toyota&model=Land+Cruiser&limit=10

Edit request3 parameters

makemodellimitAPI keyKept in memory for this page only and sent directly to the API.

curl "https://api.oldcarsdata.com/auctions?make=Toyota&model=Land+Cruiser&limit=10" \
  -H "Authorization: Bearer $OCD_API_KEY"

Sends directly from your browser

Response example200

{
  "data": [
    {
      "id": 12345,
      "title": "1970 Toyota Land Cruiser FJ40",
      "auction_status": "sold",
      "price": 45000,
      "year": 1970,
      "listing_make": "Toyota",
      "listing_model": "Land Cruiser"
    }
  ],
  "meta": { "page": 1, "limit": 10 }
}

Your key is never saved to local storage or sent through the docs server.

Looking for active listings?

Use GET /auctions/live to list currently active auctions. Live auctions are currently in beta and include supported Bring a Trailer (bringatrailer), Cars & Bids (carsandbids), Hemmings (hemmings), Hagerty (hagerty), PCAR Market (pcarmarket), All Collector Cars (acc), Gooding & Co (gooding), RM Sotheby's (rmsothebys), Sotheby's Motorsport (sothebysmotorsport), Car & Classic (carandclassic), The Market (themarket), MB Market (mbmarket), Mecum Auctions (mecum), and PistonHeads (pistonheads) listings.

How to choose query parameters

Browse by make/model: Pass make, model, both, or neither. Use GET /makes and GET /models for exact normalized strings. On MCP, use list_makes and list_models the same way.

VIN lookup: Pass vin for an exact raw match as stored. You can still add status, source, keyword, year/price filters, etc.

Seller lookup: Pass seller_username for an exact match. Combine with other filters as needed.

Reference calls to /makes and /models do not count toward your API query limit. GET /auctions does count.

Authentication#

This endpoint requires authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Starter Plan Limitation: Starter plan users are limited to the latest 20 auctions regardless of filters or pagination. Upgrade to a paid plan for full historical data access.

Use cursor pagination for sequential exports

Set pagination=cursor for large or sequential result sets. Cursor mode avoids exact-count and deep-offset work. Keep the same filters, sort, and direction, then pass each returned next_cursor to the following request. Existing integrations continue to use numbered pages by default.

Cursor consistency

Cursor pagination traverses the live completed-auction dataset; it does not materialize a point-in-time snapshot. Completed records rarely change, but a record updated, inserted, or removed during a multi-page traversal can repeat or be omitted. De-duplicate records by auction id, and do not treat a live traversal as a complete point-in-time export.

Auction ending precision

Use auction_end_at together with auction_end_precision. A precision of exact means the ending time is known. A precision of date means only the calendar date is known, so the 00:00:00 time is a normalization placeholder—not a known midnight ending. A null precision means no ending value is known. auction_end_date is deprecated.

Rules#

No required vehicle anchor: make, model, vin, and seller_username are all optional.
vin / seller_username: Exact string match against the stored value (not normalized).
Combining filters: status, source, keyword, year_min / year_max, price_min / price_max, sort, direction, pagination fields, and limit combine with any vehicle, VIN, or seller filters. Example: ?model=911&status=sold or ?seller_username=classic_seller&source=bringatrailer.
Broad searches: If no filters are provided, the endpoint returns paginated completed auction results sorted by auction_end_at by default. Date-only values use their normalized midnight placeholder for sorting, and records without an ending value sort last.
Pagination modes: page is the backward-compatible default and returns exact totals. cursor supports sort=date, returns no exact total, and is recommended when reading multiple pages.

Request Parameters#

Field	Type	Required	Description
`Authorization`#	header	Yes	Bearer token with your API key: `Bearer YOUR_API_KEY`
`make`#	string	No	Exact normalized make from Get Makes.
`vin`#	string	No	Exact VIN (raw).
`seller_username`#	string	No	Exact seller username.
`model`#	string	No	Normalized model from Get Models.
`year_min`#	integer	No	Minimum year filter (inclusive)
`year_max`#	integer	No	Maximum year filter (inclusive)
`price_min`#	integer	No	Minimum price filter (inclusive)
`price_max`#	integer	No	Maximum price filter (inclusive)
`status`#	enum	No	Auction status filter. Options: "sold", "result unavailable", "reserve not met", "canceled", "unknown"
`source`#	string	No	Source platform filter. Values: `bringatrailer`, `carsandbids`, `hemmings`, `autohunter`, `hagerty`, `pcarmarket`, `acc`, `gooding`, `rmsothebys`, `barrettjackson`, `sothebysmotorsport`, `carandclassic`, `themarket`, `broadarrow`, `mbmarket`, `mecum`, `pistonheads`, `collectingcars`, `bonhams`
`keyword`#	string	No	Search keyword to match in title and description (case-insensitive)
`sort`#	enum	No	Sort field. Options: "date" (default, ordered by `auction_end_at`), "price", "year", "bids"
`direction`#	enum	No	Sort direction. Options: "asc", "desc" (default)
`pagination`#	enum	No	Pagination mode: deprecated `page` (default) or recommended `cursor`. Cursor mode supports `sort=date`.
`cursor`#	string	No	Opaque `next_cursor` from the previous cursor response. Repeat the same filters, sort, and direction. The traversal expires 24 hours after its first cursor is issued. Traversal uses live data; changed records can repeat or be omitted.
`page`#	integer	No	Deprecated. Page number for `pagination=page`. Minimum: 1, default: 1. In cursor mode it may be omitted or set to 1.
`limit`#	integer	No	Number of results per page. Range: 1-100, default: 50

Code Examples#

Mode A — Make and model (cURL)#

bash

curl "https://api.oldcarsdata.com/auctions?make=Toyota&model=Land+Cruiser&limit=10" \  -H "Authorization: Bearer YOUR_API_KEY"

Mode B — VIN only (cURL)#

bash

curl "https://api.oldcarsdata.com/auctions?vin=WP0AB0911FS100123" \  -H "Authorization: Bearer YOUR_API_KEY"

Mode C — Seller only (cURL)#

bash

curl "https://api.oldcarsdata.com/auctions?seller_username=classic_seller" \  -H "Authorization: Bearer YOUR_API_KEY"

Cursor pagination (cURL)#

Start without a cursor:

bash

curl "https://api.oldcarsdata.com/auctions?make=Toyota&pagination=cursor&limit=100" \  -H "Authorization: Bearer YOUR_API_KEY"

For the next page, repeat the filters and URL-encode the returned cursor:

bash

curl --get "https://api.oldcarsdata.com/auctions" \  -H "Authorization: Bearer YOUR_API_KEY" \  --data-urlencode "make=Toyota" \  --data-urlencode "pagination=cursor" \  --data-urlencode "limit=100" \  --data-urlencode "cursor=NEXT_CURSOR"

JavaScript (make/model)#

javascript

const response = await fetch(  'https://api.oldcarsdata.com/auctions?make=Toyota&model=Land+Cruiser&limit=10',  {    headers: {      'Authorization': 'Bearer YOUR_API_KEY'    }  });const data = await response.json();

JavaScript (VIN)#

javascript

const params = new URLSearchParams({ vin: 'WP0AB0911FS100123' });const response = await fetch(  `https://api.oldcarsdata.com/auctions?${params}`,  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } });const data = await response.json();

JavaScript (seller)#

javascript

const params = new URLSearchParams({ seller_username: 'classic_seller' });const response = await fetch(  `https://api.oldcarsdata.com/auctions?${params}`,  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } });const data = await response.json();

Python (make/model)#

python

import requestsresponse = requests.get(    'https://api.oldcarsdata.com/auctions',    params={'make': 'Toyota', 'model': 'Land Cruiser', 'limit': 10},    headers={'Authorization': 'Bearer YOUR_API_KEY'})data = response.json()

Python (VIN)#

python

import requestsresponse = requests.get(    'https://api.oldcarsdata.com/auctions',    params={'vin': 'WP0AB0911FS100123'},    headers={'Authorization': 'Bearer YOUR_API_KEY'})data = response.json()

Python (seller)#

python

import requestsresponse = requests.get(    'https://api.oldcarsdata.com/auctions',    params={'seller_username': 'classic_seller'},    headers={'Authorization': 'Bearer YOUR_API_KEY'})data = response.json()

Success Response (200)#

Auctions retrieved successfully. The deprecated numbered-page response remains the default for backward compatibility and includes Deprecation and Link: rel="deprecation" response headers:

json

{  "data": [    {      "id": 12345,      "source": "bringatrailer",      "url": "https://bringatrailer.com/listing/...",      "title": "1970 Toyota Land Cruiser FJ40",      "auction_status": "sold",      "price": 45000,      "currency": "USD",      "auction_end_at": "2024-01-15 21:00:00",      "auction_end_precision": "exact",      "mileage": 85000,      "vin": "FJ40123456",      "title_status": "clean",      "city": "Los Angeles",      "state": "CA",      "zip": "90001",      "seller_username": "seller123",      "year": 1970,      "has_reserve": true,      "listing_make": "Toyota",      "listing_model": "Land Cruiser",      "engine": "4.2L I6",      "drivetrain": "4WD",      "transmission": "Manual",      "body_style": "SUV",      "exterior_color": "Beige",      "standard_exterior_color": "Beige",      "interior_color": "Brown",      "standard_interior_color": "Brown",      "seller_type": "private",      "ocd_make_name": "Toyota",      "ocd_model_name": "Land Cruiser",      "description": "Well-maintained FJ40...",      "ownership_history": "Original owner",      "modifications": ["Lift kit", "Aftermarket wheels"],      "known_flaws": ["Minor rust on rear bumper"],      "recent_service_history": ["Oil change 2023", "Brake service 2023"],      "listing_details": ["Clean title", "No accidents"],      "created_at": "2024-01-10 10:00:00",      "featured_image_url": "https://bringatrailer.com/wp-content/uploads/2024/01/1970_toyota_land-cruiser_fj40_12345.jpg",      "stats": {        "views": 1250,        "watches": 45,        "likes": 12,        "bids": 23      }    }  ],  "meta": {    "total": 150,    "page": 1,    "limit": 10,    "total_pages": 15  }}

Cursor mode returns traversal metadata instead of exact totals:

json

{  "data": [    {      "id": 12345,      "title": "1970 Toyota Land Cruiser FJ40",      "auction_status": "sold",      "auction_end_at": "2024-01-15 21:00:00",      "auction_end_precision": "exact"    }  ],  "meta": {    "pagination": "cursor",    "limit": 100,    "has_more": true,    "next_cursor": "OPAQUE_CURSOR"  }}

Response Fields#

Field	Type	Description
`data`#	array	Array of auction objects
`data[].id`#	number	Unique auction identifier
`data[].source`#	string \| null	Source platform name
`data[].url`#	string \| null	URL to the auction listing
`data[].title`#	string \| null	Auction listing title
`data[].auction_status`#	enum	Status: "sold", "result unavailable", "reserve not met", "canceled", "unknown"
`data[].price`#	number \| null	Final sale price or bid amount
`data[].currency`#	string \| null	ISO 4217 currency code (e.g. "USD", "CAD")
`data[].auction_end_date`#	string \| null	Deprecated. Legacy date-only ending value in `YYYY-MM-DD` format. Use `auction_end_at` with `auction_end_precision`.
`data[].auction_end_at`#	string \| null	Auction ending wall-clock value in `YYYY-MM-DD HH:mm:ss[.ffffff]` format; no UTC offset is included. Consult `auction_end_precision` before interpreting the time component.
`data[].auction_end_precision`#	`"exact"` \| `"date"` \| null	Precision of `auction_end_at`. `exact` means the ending time is known. `date` means only the calendar date is known and `00:00:00` is a normalization placeholder, not a known midnight ending. Null means no ending value is known.
`data[].mileage`#	number \| null	Vehicle mileage
`data[].vin`#	string \| null	Vehicle identification number
`data[].title_status`#	string \| null	Title status (e.g., "clean", "salvage")
`data[].city`#	string \| null	Vehicle location city
`data[].state`#	string \| null	Vehicle location state
`data[].zip`#	string \| null	Vehicle location ZIP code
`data[].seller_username`#	string \| null	Seller username
`data[].year`#	number \| null	Vehicle model year
`data[].has_reserve`#	boolean \| null	Whether the auction had a reserve price
`data[].listing_make`#	string \| null	Make name from listing
`data[].listing_model`#	string \| null	Model name from listing
`data[].ocd_make_name`#	string \| null	Normalized make name
`data[].ocd_model_name`#	string \| null	Normalized model name
`data[].engine`#	string \| null	Engine specification
`data[].drivetrain`#	string \| null	Drivetrain type
`data[].transmission`#	string \| null	Transmission type
`data[].body_style`#	string \| null	Vehicle body style
`data[].exterior_color`#	string \| null	Exterior color as listed
`data[].standard_exterior_color`#	string \| null	Normalized exterior color
`data[].interior_color`#	string \| null	Interior color as listed
`data[].standard_interior_color`#	string \| null	Normalized interior color
`data[].seller_type`#	string \| null	Seller type (e.g., "private", "dealer")
`data[].description`#	string \| null	Listing description text
`data[].ownership_history`#	string \| null	Ownership history information
`data[].modifications`#	array	Array of modification descriptions
`data[].known_flaws`#	array	Array of known flaw descriptions
`data[].recent_service_history`#	array	Array of recent service history entries
`data[].listing_details`#	array	Array of listing detail strings
`data[].created_at`#	string \| null	Record creation wall-clock timestamp in `YYYY-MM-DD HH:mm:ss[.ffffff]` format; no UTC offset is included.
`data[].featured_image_url`#	string \| null	URL to the featured image
`data[].stats`#	object	Auction engagement statistics
`data[].stats.views`#	number \| null	Number of views
`data[].stats.watches`#	number \| null	Number of watchers
`data[].stats.likes`#	number \| null	Number of likes/comments
`data[].stats.bids`#	number \| null	Number of bids
`meta`#	object	Metadata for the selected pagination mode
`meta.total`#	number	Exact matching total in page mode
`meta.page`#	number	Current page number in page mode
`meta.limit`#	number	Number of results per page
`meta.total_pages`#	number	Exact number of pages in page mode
`meta.pagination`#	string	`"cursor"` in cursor mode
`meta.has_more`#	boolean	Whether another cursor page is available
`meta.next_cursor`#	string \| null	Opaque token for the next cursor page

Error Responses#

400Invalid requestCheck required values and accepted formats.

401UnauthorizedAdd a valid Bearer API key.

403Access deniedVerify your email and confirm plan access.

429Rate limit reachedWait for the reset window before retrying.

Field	Type	Description
`error`#	string	Error type identifier (e.g., "Validation Error", "HTTP Error")
`message`#	string	Human-readable error message
`details`#	object	Validation error details (only on 400 responses). Keys are field names, values are arrays of error messages.

400 — Validation Error:

json

{  "error": "Validation Error",  "message": "limit: Number must be less than or equal to 100",  "details": {    "limit": ["Number must be less than or equal to 100"]  }}

401 — Unauthorized:

json

{  "error": "Unauthorized",  "message": "API key is required. Provide it via Authorization: Bearer <key> header"}