# LiveAuctioneers — auction lots, sold archive, sales, houses

> Search lots that are open for bidding or coming up, across thousands of auction houses. Filters: category, house, country, state, sale type, estimate range, current-bid range. Give `query` or at least one filter.
> ReefAPI engine `liveauctioneers` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/liveauctioneers/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/liveauctioneers/v1/search — 2 credits
Search lots that are open for bidding or coming up, across thousands of auction houses. Filters: category, house, country, state, sale type, estimate range, current-bid range. Give `query` or at least one filter.

**Parameters:**
- `query` (string, optional) — Keywords, as typed on liveauctioneers.com (e.g. 'rolex daytona', 'tiffany lamp'). Optional when a filter is given.
- `category` (enum, optional) — Top-level category. Unknown values are refused (the source would silently ignore them and return everything). [one of: art, collectibles, fashion, furniture, home_decor, jewelry]
- `house_id` (integer, optional) — Restrict to one auction house — the `house_id` of a row or of `auction_house`.
- `country` (string, optional) — Two-letter country of the auction house (US, UK, DE, CA …). `GB` is accepted for the United Kingdom.
- `state` (string, optional) — Two-letter US state / province code of the house (NY, CA, FL, ON …).
- `sale_type` (enum, optional) — Kind of sale. [one of: live, timed, timed_plus, buy_now]
- `min_estimate` (number, optional) — Lower bound on the LOW pre-sale estimate, in the lot's own currency.
- `max_estimate` (number, optional) — Upper bound on the LOW pre-sale estimate (the source filters on the low end of the range), in the lot's own currency.
- `min_bid` (number, optional) — Lowest current bid (or opening price on a lot with no bids), in the lot's own currency.
- `max_bid` (number, optional) — Highest current bid (or opening price).
- `sort` (enum, optional, default "relevance") — Order. [one of: relevance, newly_listed, sale_soonest, most_bids, estimate_high_first, bid_high_first, bid_low_first, lot_number]
- `page` (integer, optional, default 1) — 1-based page number.
- `max_results` (integer, optional, default 24) — Rows per page (the source caps a page at 120).

**Returns:** `results[]` lots (lot_id, url, title, estimate_low/high, starting_price, current_bid, bid_count, price_is, currency, sale + house + location, sale_starts_at, lot_ends_at_estimated, images) plus `total_found`, `total_is_capped`, `last_reachable_page`.

**Example request body:**
```json
{
  "query": "tiffany lamp",
  "max_results": 10
}
```

### POST https://api.reefapi.com/liveauctioneers/v1/past_results — 2 credits
The sold-lot archive: what each lot sold for (the hammer price, before the buyer's premium), when, at which house, against which estimate and opening price, and how many bids it drew. Give `query` or at least one filter.

**Parameters:**
- `query` (string, optional) — Keywords, as typed on liveauctioneers.com (e.g. 'rolex daytona', 'tiffany lamp'). Optional when a filter is given.
- `category` (enum, optional) — Top-level category. Unknown values are refused (the source would silently ignore them and return everything). [one of: art, collectibles, fashion, furniture, home_decor, jewelry]
- `house_id` (integer, optional) — Restrict to one auction house — the `house_id` of a row or of `auction_house`.
- `country` (string, optional) — Two-letter country of the auction house (US, UK, DE, CA …). `GB` is accepted for the United Kingdom.
- `state` (string, optional) — Two-letter US state / province code of the house (NY, CA, FL, ON …).
- `sale_type` (enum, optional) — Kind of sale. [one of: live, timed]
- `min_estimate` (number, optional) — Lower bound on the LOW pre-sale estimate, in the lot's own currency.
- `max_estimate` (number, optional) — Upper bound on the LOW pre-sale estimate (the source filters on the low end of the range), in the lot's own currency.
- `min_price` (number, optional) — Lowest hammer price, in the lot's own currency.
- `max_price` (number, optional) — Highest hammer price, in the lot's own currency.
- `sold_after` (string, optional) — Sale date on or after (YYYY-MM-DD, UTC).
- `sold_before` (string, optional) — Sale date on or before (YYYY-MM-DD, UTC).
- `sort` (enum, optional, default "relevance") — Order. [one of: relevance, sale_date_desc, price_high_first, price_low_first]
- `page` (integer, optional, default 1) — 1-based page number.
- `max_results` (integer, optional, default 24) — Rows per page (the source caps a page at 120).

**Returns:** `results[]` sold lots with `hammer_price`, `final_bid`, estimates, `starting_price`, `bid_count`, `winning_bidder_id`, sale date and house.

**Example request body:**
```json
{
  "query": "tiffany lamp",
  "sort": "price_high_first",
  "max_results": 10
}
```

### POST https://api.reefapi.com/liveauctioneers/v1/detail — 3 credits
One lot in full: description, condition report, dimensions, category path, maker, materials, every image, the hammer price and bid history of an ended lot, and the sale's buyer's premium schedule, bid increments and location.

**Parameters:**
- `lot_id` (integer, required) — The `lot_id` of a search or archive row (the number in /item/<id>_…).

**Returns:** The lot row plus `description`, `condition_report`, `dimensions`, `weight`, `categories[]`, `makers[]`, `materials[]`, `origins[]`, `style_periods[]`, `bid_history[]` (filled after close), `sale{buyers_premium_schedule, bid_increments, location}`.

**Example request body:**
```json
{
  "lot_id": 135377389
}
```

### POST https://api.reefapi.com/liveauctioneers/v1/auction — 3 credits
One sale (catalogue): its terms, buyer's premium schedule, bid increments, location and its lots, page by page.

**Parameters:**
- `sale_id` (integer, required) — The `sale_id` of a lot row (the number in /catalog/<id>).
- `page` (integer, optional, default 1) — 1-based page number.
- `max_results` (integer, optional, default 50) — Lots per page.

**Returns:** `sale{…}` plus `lots[]` (same row shape as search) and `total_lots`, `sold_on_page`, `passed_on_page`.

**Example request body:**
```json
{
  "sale_id": 259954,
  "max_results": 20
}
```

### POST https://api.reefapi.com/liveauctioneers/v1/auction_house — 3 credits
One auction house: address, website, business contact, review scores by dimension, number of open and finished sales, and its upcoming sales with their buyer's premium.

**Parameters:**
- `house_id` (integer, required) — The `house_id` of a lot row or a suggestion (the number in /auctioneer/<id>/).

**Returns:** `house{name, address, website, email, phone, member_since, rating{…}, sales_open, sales_finished}` and `upcoming_sales[]`.

**Example request body:**
```json
{
  "house_id": 7169
}
```

### POST https://api.reefapi.com/liveauctioneers/v1/suggest — 1 credit
Search-box suggestions: completed queries and matching auction houses (with their `house_id`).

**Parameters:**
- `query` (string, required) — At least 3 characters.

**Returns:** `suggestions[]` {text, kind: query|house, house_id}.

**Example request body:**
```json
{
  "query": "rolex day"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=liveauctioneers
- Human docs page: https://reefapi.com/docs/liveauctioneers
- Overview page: https://reefapi.com/liveauctioneers-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt