Looking for the overview — what this API returns, what it costs, and a call you can run without a key? See the Invaluable API page →

docs / invaluable

Invaluable

base /invaluable/v18 endpoints

post/invaluable/v1/search1 credit

Search the lots that are open for bidding right now across ~6 900 auction houses worldwide — roughly 289 000 of them. Every filter is optional. Each row keeps its own currency and separates the four prices an auction lot has: `estimate_low`/`estimate_high` (the house's estimate), `starting_bid` (the opening ask, which is what the headline figure is while nobody has bid), `current_bid` (only once `bid_count` >= 1) and `hammer_price` (set only when the lot has actually sold). `price_is` names which of them the live figure is.

Parameter		Allowed / range	Description
query	optional	—	Free-text search over the lot title, the house's description and the artist name (e.g. 'rolex daytona', 'picasso lithograph', 'meissen figurine'). Leave it out to browse everything.
category	optional	SG2BIX3JPJ · BQWOG3FLWY · 66MNH3RVXU · HV9SJ0PETO · YKGNZXS2MH · URF9IESAHL · TJYLLGLDKA · 0HV8BV6K8Y · WIARM9WZTW · 5P1KWJO0ML · 8NR4UKTNYX · CNWPZEY4P5 · Q2ENTPZUZ4 · MU8Q47SBT3 · WXJEP9TUWL	Restrict to one of Invaluable's 15 top-level categories. Takes the category name or its 10-character id from the `categories` action.
subcategory	optional	—	Restrict further to one category inside `category` (e.g. "Watches, Men's", 'Painting', 'Rings'). 🔴 Take the value from the `categories` action, NOT from the site's own menu: the menu and the lot index spell several of these differently (the menu's "Men's Watches" is "Watches, Men's" in the index) and a spelling the index does not use returns no rows.
house_id	optional	—	Restrict to one auction house, by its 10-character Invaluable id. The `auction_house` action returns ids together with names, countries and upcoming-sale counts.
artist_id	optional	—	Restrict to one artist/maker, by its 10-character Invaluable id. The `artists` action returns ids with the artist's lifetime, upcoming and past lot counts.
country	optional	—	Restrict to the auction houses of one country. Takes a two-letter code for the 37 mapped markets (US, GB, DE, FR, HK, KR, AU…) or the country's full name exactly as Invaluable writes it.
state	optional	—	Restrict to one US state or other first-level region, as Invaluable writes it (e.g. 'New York', 'Florida', 'New South Wales'). Live lots only — the archive does not index it.
currency	optional	—	Restrict to lots priced in one currency. 🔴 Nothing in this API is converted: every amount is in the lot's own currency and one unfiltered page routinely mixes USD, EUR, GBP, AUD, HKD and KRW.
sale_type	optional	live · timed · view_only	Restrict by how the sale is run.
online_only	optional	—	true = only lots in sales that exist only online.
with_images_only	optional	—	true = only lots that carry a photo.
min_bid	optional	0–	Lowest acceptable live figure (the opening ask on a lot with no bids, the current bid once there is one), in the lot's OWN currency — combine with `currency` to compare like with like.
max_bid	optional	0–	Highest acceptable live figure, in the lot's own currency.
min_estimate	optional	0–	Lowest acceptable `estimate_low`, in the lot's own currency.
max_estimate	optional	0–	Highest acceptable `estimate_low`, in the lot's own currency.
min_bids	optional	0–	Only lots that already have at least this many bids. `min_bids=1` is how you ask for lots where the headline figure is a real bid rather than the opening ask.
starts_after	optional	—	Only sales starting on or after this UTC date (YYYY-MM-DD).
starts_before	optional	—	Only sales starting on or before this UTC date (YYYY-MM-DD).
sort = ending_soonest	optional	ending_soonest · newly_listed · relevance · bid_low_first · bid_high_first · fewest_bids · most_bids	Row order. The bid orders are ranked by Invaluable across currencies, so the sequence is not monotonic in any single currency.
page = 1	optional	1–25000	1-based page. Invaluable serves at most 25,000 lots per query, so the last reachable page is 25,000/max_results — narrow the query (category, house, country, price band) to reach deeper lots.
max_results = 50	optional	1–200	Rows per page, 1-200.

Try in playground →

post/invaluable/v1/past_results1 credit

Search Invaluable's realised-price archive — what lots ACTUALLY SOLD FOR, around 10 million of them, going back two decades. `hammer_price` is the realised price BEFORE the buyer's premium (`amounts_include_buyers_premium` is false on every row; `detail` returns the premium itself). Only lots whose sale has actually CLOSED are returned — and by default only those that realised money, because a closed lot nobody bid on did not sell. Pass `sold_only=false` to get the passed lots too and read `sold` per row, which is how you measure a house's or a category's sell-through.

Parameter		Allowed / range	Description
query	optional	—	Free-text search over the lot title, the house's description and the artist name (e.g. 'rolex daytona', 'picasso lithograph', 'meissen figurine'). Leave it out to browse everything.
category	optional	SG2BIX3JPJ · BQWOG3FLWY · 66MNH3RVXU · HV9SJ0PETO · YKGNZXS2MH · URF9IESAHL · TJYLLGLDKA · 0HV8BV6K8Y · WIARM9WZTW · 5P1KWJO0ML · 8NR4UKTNYX · CNWPZEY4P5 · Q2ENTPZUZ4 · MU8Q47SBT3 · WXJEP9TUWL	Restrict to one of Invaluable's 15 top-level categories. Takes the category name or its 10-character id from the `categories` action.
subcategory	optional	—	Restrict further to one category inside `category` (e.g. "Watches, Men's", 'Painting', 'Rings'). 🔴 Take the value from the `categories` action, NOT from the site's own menu: the menu and the lot index spell several of these differently (the menu's "Men's Watches" is "Watches, Men's" in the index) and a spelling the index does not use returns no rows.
house_id	optional	—	Restrict to one auction house, by its 10-character Invaluable id. The `auction_house` action returns ids together with names, countries and upcoming-sale counts.
artist_id	optional	—	Restrict to one artist/maker, by its 10-character Invaluable id. The `artists` action returns ids with the artist's lifetime, upcoming and past lot counts.
country	optional	—	Restrict to the auction houses of one country. Takes a two-letter code for the 37 mapped markets (US, GB, DE, FR, HK, KR, AU…) or the country's full name exactly as Invaluable writes it.
currency	optional	—	Restrict to lots priced in one currency. 🔴 Nothing in this API is converted: every amount is in the lot's own currency and one unfiltered page routinely mixes USD, EUR, GBP, AUD, HKD and KRW.
sold_only = true	optional	—	true (default) = only lots that realised a price. false = also the lots that closed unsold, so you can measure the sell-through of a house or a category.
min_price	optional	0–	Lowest acceptable `hammer_price`, in the lot's OWN currency — combine with `currency` to compare like with like.
max_price	optional	0–	Highest acceptable `hammer_price`, in the lot's own currency.
sold_after	optional	—	Only sales held on or after this UTC date (YYYY-MM-DD).
sold_before	optional	—	Only sales held on or before this UTC date (YYYY-MM-DD).
with_images_only	optional	—	true = only lots that carry a photo.
sort = sale_date_desc	optional	sale_date_desc · sale_date_asc · price_high_first · price_low_first	Row order. The price orders are ranked by Invaluable across currencies, so the sequence is not monotonic in any single currency.
page = 1	optional	1–25000	1-based page. Invaluable serves at most 25,000 lots per query, so the last reachable page is 25,000/max_results — narrow the query (category, house, country, price band) to reach deeper lots.
max_results = 50	optional	1–200	Rows per page, 1-200.

Try in playground →

post/invaluable/v1/detail1 credit

One lot in full: the catalogue text the house wrote (description, condition, provenance, literature, exhibition history, dimensions, medium, signature, circa), every photo, and the complete money picture — the estimate, the opening ask, the current bid, the realised price, the buyer's premium amount, the derived premium rate, the total with premium, and the SALE's own `results_include_premium` declaration plus its full tiered premium schedule. Takes the lot id or any Invaluable lot URL.

Parameter		Allowed / range	Description
lot	required	—	The lot's 10-character Invaluable id, or a full lot URL such as https://www.invaluable.com/auction-lot/…-c-4035350c64
include_sale_terms = true	optional	—	true (default) also reads the lot's sale for the buyer's-premium schedule, the bid increments, the conditions of sale and the shipping/payment notes. false skips that second call.

Try in playground →

post/invaluable/v1/auction1 credit

One sale (an auction catalogue) with its terms, or the list of sales coming up across the whole site. With `sale_id` you get the sale's own record: when it starts in UTC, where, which house, the full buyer's-premium schedule, the bid increments, the conditions of sale, and whether the published results include the premium. Without it you get the upcoming-sale calendar.

Parameter		Allowed / range	Description
sale_id	optional	—	The sale's 10-character Invaluable catalogue id, or any /catalog/<id> URL. Leave it out for the upcoming-sale calendar.
page = 1	optional	1–500	1-based page of the upcoming-sale calendar.
max_results = 25	optional	1–100	Sales per page of the calendar, 1-100.

Try in playground →

post/invaluable/v1/auction_house1 credit

Find auction houses or read one. With `query`/`country` you search the 6 949-house directory and get each house's id — which is what the `house_id` filter on `search` and `past_results` takes — together with its live and archived lot counts. With `house_id` you get that house's own record: its business address, its country, the year it joined, plus its upcoming and most recent past sales.

Parameter		Allowed / range	Description
query	optional	—	Name search over the house directory (e.g. 'christie', 'bonhams', 'dorotheum').
house_id	optional	—	Restrict to one auction house, by its 10-character Invaluable id. The `auction_house` action returns ids together with names, countries and upcoming-sale counts.
country	optional	—	Restrict to the auction houses of one country. Takes a two-letter code for the 37 mapped markets (US, GB, DE, FR, HK, KR, AU…) or the country's full name exactly as Invaluable writes it.
page = 1	optional	1–100	1-based page. The directory serves at most 1,000 houses per query — narrow it with `query` or `country` to reach the rest.
max_results = 25	optional	1–100	Houses per page, 1-100.

Try in playground →

post/invaluable/v1/artists1 credit

Find an artist or maker in Invaluable's 260 000-name authority file and get the id the `artist_id` filter takes, with the number of lots on the live surface and in the realised-price archive. With `artist_id` you also get the artist's record: lifetime dates, professions, known aliases and genres — which is how you tell two painters with the same surname apart before pulling their price history.

Parameter		Allowed / range	Description
query	optional	—	Name search over the artist authority file (e.g. 'picasso', 'tiffany studios').
artist_id	optional	—	Restrict to one artist/maker, by its 10-character Invaluable id. The `artists` action returns ids with the artist's lifetime, upcoming and past lot counts.
page = 1	optional	1–250	1-based page. The authority file serves at most 25,000 names per query.
max_results = 25	optional	1–100	Artists per page, 1-100.

Try in playground →

post/invaluable/v1/categories1 credit

Invaluable's taxonomy with LIVE counts: the 15 top-level categories, each with the categories beneath it and how many lots are open for bidding in each. 🔴 The site's own taxonomy endpoint and its lot index disagree on two names (it calls one 'Guns & Firearms', the index calls it 'Firearms', and 'Estate & Storage' has no lots at all), which is why every row here carries the stable id as well — the id is what the `category` filter should take.

Parameter		Allowed / range	Description
category	optional	SG2BIX3JPJ · BQWOG3FLWY · 66MNH3RVXU · HV9SJ0PETO · YKGNZXS2MH · URF9IESAHL · TJYLLGLDKA · 0HV8BV6K8Y · WIARM9WZTW · 5P1KWJO0ML · 8NR4UKTNYX · CNWPZEY4P5 · Q2ENTPZUZ4 · MU8Q47SBT3 · WXJEP9TUWL	Return only this top-level category's children.
surface = live	optional	live · archive	Which side of the site to count: 'live' = lots open for bidding, 'archive' = the realised-price archive.

Try in playground →

post/invaluable/v1/suggest1 credit

Invaluable's own search suggestions for a partial phrase, each with how many lots it matches on the live surface AND in the realised-price archive. Useful for turning a vague term into a query that actually has data behind it — 'rolex' returns 496 live and 217 762 archived lots, 'rolex daytona' 13 and 13 473.

Parameter		Allowed / range	Description
query	required	—	The partial phrase to complete (e.g. 'rol', 'chinese vas').
max_results = 10	optional	1–50	Suggestions to return, 1-50.

Try in playground →

Example request · search

curl -X POST https://api.reefapi.com/invaluable/v1/search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"rolex","max_results":10}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}

Built for volume

5M+ requests a day

Measured at 60 requests a second across the fleet, with no central bottleneck. Volume pricing is on request, and per-key limits are raised for high-volume accounts.

Missing a source?

We build it

Tell us a site we do not cover yet and it becomes an engine. A customer asked for bestprice.gr on a Sunday and it was in the catalog the next day.

Support

2 minute median reply

Median time from a question in the live chat to the first answer, measured across every answered conversation. Setup help included, no support tier to buy.

One key, one balance

Every API included

No per-site plans and no separate subscriptions. One key and one credit pool across the whole catalog, so adding a source costs nothing up front.

Planning something large? Tell us the volume and the sources and we will come back with what it costs and what we would have to build.

Comparing scraping APIs?ReefAPI vs ScrapingBee ReefAPI vs ZenRows ReefAPI vs Apify