Docs

Get Auctions

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

GET

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.

Response

application/json

Auctions retrieved successfully

Request Parameters

Field	Type	Required	Description
Authorization	header	Required	Bearer token with your API key: Bearer YOUR_API_KEY
make	string	Required	Make name (e.g., "Toyota"). Minimum length: 1 character.
model	string	-	Model name to filter by
year_min	integer	-	Minimum year filter (inclusive)
year_max	integer	-	Maximum year filter (inclusive)
price_min	integer	-	Minimum price filter (inclusive)
price_max	integer	-	Maximum price filter (inclusive)
status	enum	-	Auction status filter. Options: "sold", "bid to", "reserve not met", "canceled", "unknown"
source	string	-	Source platform filter (e.g., "bringatrailer")
keyword	string	-	Search keyword to match in title and description (case-insensitive)
sort	enum	-	Sort field. Options: "date" (default), "price", "year", "bids"
direction	enum	-	Sort direction. Options: "asc", "desc" (default)
page	integer	-	Page number for pagination. Minimum: 1, default: 1
limit	integer	-	Number of results per page. Range: 1-100, default: 50

Success Response Fields (200)

Field	Type	Required	Description
data	array<object>	Required	Array of auction objects
data[].id	number	Required	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	-	Auction status: "sold", "bid to", "reserve not met", "canceled", "unknown"
data[].price	number \| null	-	Final sale price or bid amount
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<string>	-	Array of modification descriptions
data[].known_flaws	array<string>	-	Array of known flaw descriptions
data[].recent_service_history	array<string>	-	Array of recent service history entries
data[].listing_details	array<string>	-	Array of listing detail strings
data[].created_at	string \| null	-	Record creation timestamp (ISO 8601 format)
data[].featured_image_url	string \| null	-	URL to the featured image of the auction
data[].stats	object	Required	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	Required	Pagination metadata
meta.total	number	Required	Total number of matching auctions
meta.page	number	Required	Current page number
meta.limit	number	Required	Number of results per page
meta.total_pages	number	Required	Total number of pages

Error Response Fields

Field	Type	Required	Description
error	string	Required	Error type identifier. Common values: "Validation Error", "HTTP Error", "Database Error", "Internal Server Error"
message	string	Required	Human-readable error message describing what went wrong
details	object<string, string[]>	-	Additional validation error details. Only present for 400 Validation Error responses. Keys are field names, values are arrays of error messages for that field

Get Get Auctions

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();

Example Response

200

400

401

403

500

503

504

{
  "data": [
    {
      "id": 12345,
      "source": "bringatrailer",
      "url": "https://bringatrailer.com/listing/...",
      "title": "1970 Toyota Land Cruiser FJ40",
      "auction_status": "sold",
      "price": 45000,
      "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
  }
}