Invaluable APIinvaluable.com ↗
Access auction lot listings, artist profiles, and auction house data from Invaluable.com via 8 endpoints. Search upcoming and past lots, bids, and catalog details.
What is the Invaluable API?
The Invaluable.com API provides access to fine art and collectibles auction data through 8 endpoints covering lot search, artist profiles, auction house details, and catalog browsing. The search_items endpoint returns paginated auction lots with fields like lotRef, currentBid, houseName, and artistName, filtering across both upcoming and archived sales. Live bidding fields — currentBidAmount, bidCount, and isClosed — are available per lot via get_item_detail.
curl -X GET 'https://api.parse.bot/scraper/03ac36d1-735f-4409-8428-86a450ee4b7a/search_items?page=0&past=False&limit=5&query=painting' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace invaluable-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Invaluable Auction API — browse lots, artists, and auction houses."""
from parse_apis.invaluable_auction_api import Invaluable, Past, LotNotFound
client = Invaluable()
# Search upcoming lots for a keyword, capped at 5 results.
for lot in client.lots.search(query="painting", limit=5):
print(lot.title, lot.current_bid, lot.currency_code)
# Find an artist and explore their upcoming lots.
artist = client.artists.search(query="Picasso", limit=1).first()
if artist:
print(artist.display_name, artist.total_count, artist.genres)
for upcoming in artist.upcoming_lots.list(limit=3):
print(upcoming.title, upcoming.current_bid, upcoming.house_name)
# Get full detail on a single lot, with typed-error handling.
try:
detail = client.lotdetails.get(lot_ref="96C8DE54B0")
print(detail.title, detail.current_bid_amount, detail.bid_count, detail.is_closed)
except LotNotFound as exc:
print(f"Lot not found: {exc.lot_ref}")
# Browse auction houses matching a keyword.
house = client.auctionhouses.search(query="Christie", limit=1).first()
if house:
print(house.house_name, house.country_name)
# Walk lots inside a catalog by constructing a Catalog from its ref.
catalog = client.catalog(catalog_ref="78B2YSVOEH")
for cat_lot in catalog.lots.list(limit=3):
print(cat_lot.title, cat_lot.current_bid)
print("exercised: lots.search / artists.search / artist.upcoming_lots.list / lotdetails.get / auctionhouses.search / catalog.lots.list")
Full-text search across auction lots. Returns upcoming lots by default; set past=true for archived/sold lots. Each lot carries bid state, category hierarchy, and auction-house metadata. Paginated via page (0-based); server caps at 5000 pages.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (0-based). |
| past | boolean | When true, searches past/archived lots instead of upcoming ones. |
| limit | integer | Results per page (max varies by server). |
| query | string | Search keyword matched against lot title, description, and category names. |
{
"type": "object",
"fields": {
"page": "integer current page number (0-based)",
"items": "array of auction lot objects with fields like lotRef, lotTitle, currentBid, bidCount, houseName, artistName, catalogRef, currencyCode",
"total": "integer total number of matching lots",
"nbPages": "integer total number of pages available"
},
"sample": {
"data": {
"page": 0,
"items": [
{
"lotRef": "96C8DE54B0",
"bidCount": 12,
"location": "Falls Church, VA, US",
"lotTitle": "2 Indian miniature paintings on paper.",
"houseName": "Quinn's Auction Galleries",
"artistName": "",
"catalogRef": "78B2YSVOEH",
"currentBid": 700,
"categoryName": "Indian & South Asian",
"currencyCode": "USD",
"currencySymbol": "$"
}
],
"total": 39866,
"nbPages": 5000
},
"status": "success"
}
}About the Invaluable API
Lot Search and Detail
The search_items endpoint accepts a query string, a past boolean to toggle between upcoming and archived lots, and standard page/limit pagination. Each result object includes lotRef, lotTitle, currentBid, houseName, artistName, and catalogRef. Passing past=true switches the result set to closed auctions, making it possible to build price history queries. Individual lot detail is available via get_item_detail, which requires a lotRef and returns live fields including currentBidAmount, bidCount, isClosed, currencyCode, and a text description.
Artists and Auction Houses
list_artists searches the artist database by keyword and returns objects with artistRef, displayName, totalCount, upcomingCount, pastCount, and genres. For most queries all results fit on page 0; pagination beyond that typically returns empty arrays. get_artist_detail accepts an artistRef and returns the same shape. get_upcoming_lots_by_artist accepts an artistRef and returns only lots from upcoming auctions attributed to that artist — past lots are not included in this endpoint.
Auction houses follow the same two-endpoint pattern. list_auction_houses accepts a query and returns objects with houseRef, houseName, and countryName. get_auction_house_detail expands on that with address (street, city, region, country, postalCode), rating, reviewCount, houseLogo, description, and sellerSince.
Catalog Browsing
get_auction_detail accepts a catalogRef (found in search_items results under catalogRef) and returns all lots in that specific auction catalog, paged via page and limit. The endpoint checks both upcoming and archived catalogs, returning whichever set has results. This makes it straightforward to pull a complete lot list for any single sale event.
The Invaluable API is a managed, monitored endpoint for invaluable.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when invaluable.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official invaluable.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track live bid counts and current bid amounts on specific lots using
get_item_detailfieldscurrentBidAmountandbidCount. - Build a sold-price database for a category by running
search_itemswithpast=trueand storingcurrentBidvalues over time. - List all upcoming lots by a given artist using
get_upcoming_lots_by_artistfiltered byartist_ref. - Profile auction houses by country using
list_auction_houseswith a region query andget_auction_house_detailfor address and rating data. - Reconstruct a full auction catalog — title, bids, artist — by feeding a
catalogRefintoget_auction_detail. - Identify prolific artists in a genre by comparing
totalCountandupcomingCountfields fromlist_artistsresults. - Monitor when a specific lot closes by polling
get_item_detailfor theisClosedboolean.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Invaluable have an official developer API?+
What does `get_item_detail` return beyond what `search_items` already includes?+
search_items returns summary fields like lotTitle, currentBid, houseName, and artistName. get_item_detail adds live bidding data (currentBidAmount, bidCount, isClosed), the full text description, and explicit currencyCode and currencySymbol fields.Does `get_upcoming_lots_by_artist` also return past/sold lots for an artist?+
past parameter pattern from search_items.Are auction results (hammer prices) available for closed lots?+
currentBidAmount field on get_item_detail reflects the winning bid once isClosed is true. However, there is no dedicated sold-price history endpoint — historical data is only accessible by searching archived lots via search_items with past=true. You can fork the API on Parse and add an endpoint that aggregates past results for a specific lotRef or artist if you need a structured price history feed.How does pagination work for `list_artists`?+
artists array for small result sets, so it is best to check the total field before paginating.