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

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.

Request Parameters

Field	Type	Required	Description
`Authorization`	header	Yes	Bearer token with your API key: `Bearer YOUR_API_KEY`
`make`	string	Yes	Make name (e.g., "Toyota"). Minimum length: 1 character.
`model`	string	No	Model name to filter by
`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 (e.g., "bringatrailer")
`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

cURL

bash

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

JavaScript

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

Python

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

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,
      "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[].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: String must contain at least 1 character(s)",
  "details": {
    "make": ["String must contain at least 1 character(s)"]
  }
}

401 — Unauthorized:

json

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