Get Auctions

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

GET https://api.oldcarsdata.com/auctions

How to choose query parameters

Mode A — Browse by make/model: You need make (and optionally model). Use GET /makes and GET /models for exact strings. On MCP, use list_makes and list_models the same way.

Mode B — VIN lookup: Pass vin only (exact raw match as stored). make is not required. You can still add status, source, keyword, year/price filters, etc.

Mode C — Seller lookup: Pass seller_username only (exact match). make is not required. 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.

Rules

At least one anchor: You must supply make or a non-empty vin or a non-empty seller_username. If none of these are provided, the request fails validation (400).
vin / seller_username: Exact string match against the stored value (not normalized). Whitespace-only values do not count as an anchor; you still need make in that case.
Combining filters: status, source, keyword, year_min / year_max, price_min / price_max, sort, direction, page, and limit apply in all modes. Example: ?vin=...&status=sold or ?seller_username=...&source=bringatrailer.
model without make: Allowed when using vin or seller_username; results must satisfy every filter you send (including model if present).

Request Parameters

Field	Type	Required	Description
`Authorization`	header	Yes	Bearer token with your API key: `Bearer YOUR_API_KEY`
`make`	string	Conditional	Required unless `vin` or `seller_username` is provided. Exact normalized make from Get Makes.
`vin`	string	Conditional	Exact VIN (raw). When provided (non-empty), `make` is not required.
`seller_username`	string	Conditional	Exact seller username. When provided (non-empty), `make` is not required.
`model`	string	No	Normalized model from Get Models for this make (Mode A). Optional in other modes.
`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", "bid to", "reserve not met", "canceled", "unknown"
`source`	string	No	Source platform filter. Examples: `bringatrailer`, `carsandbids`, `hagerty`, `pcarmarket`, `acc`, `allcollectorcars`, `gooding`, `rmsothebys`
`keyword`	string	No	Search keyword to match in title and description (case-insensitive)
`sort`	enum	No	Sort field. Options: "date" (default), "price", "year", "bids"
`direction`	enum	No	Sort direction. Options: "asc", "desc" (default)
`page`	integer	No	Page number for pagination. Minimum: 1, default: 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"

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 requests

response = 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 requests

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

Python (seller)

python

import requests

response = 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.

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_date": "2024-01-15",
      "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-10T10:00:00Z",
      "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
  }
}

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", "bid to", "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	Auction end date (YYYY-MM-DD format)
`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 timestamp (ISO 8601)
`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	Pagination metadata
`meta.total`	number	Total number of matching auctions
`meta.page`	number	Current page number
`meta.limit`	number	Number of results per page
`meta.total_pages`	number	Total number of pages

Error Responses

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": "make: make is required unless vin or seller_username is provided",
  "details": {
    "make": ["make is required unless vin or seller_username is provided"]
  }
}

401 — Unauthorized:

json

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