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'
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. Optionally filter by currency code, supercategory name, results-posted status, non-zero price result, or date range. Results are sorted from most recent to oldest auction date. When page_from and page_to are both provided, fetches all pages in that inclusive range and merges results into one response (capped at 100 pages). When only page_from is provided, returns that single page. When neither is provided, the page parameter is used.
| 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. |
| page_to | integer | End page of a multi-page fetch range (0-based, inclusive). Must be used with page_from. The range is capped at 100 pages. |
| timeout | integer | Maximum execution time in seconds for the HTTP request. When omitted, the default session timeout applies. |
| category | string | Filter results by supercategory name (e.g. Fine Art, Jewelry, Asian Art and Antiques). Matches the supercategoryName field on lots. When omitted, all supercategories are returned. |
| currency | string | Filter results to a specific currency code (e.g. USD, EUR, AUD, GBP). Matches the currencyCode field on lots. When omitted, all currencies are returned. |
| date_max | string | Filter to lots with auction date on or before this date. ISO format YYYY-MM-DD (e.g. 2024-12-31). When omitted, no upper date bound is applied. |
| date_min | string | Filter to lots with auction date on or after this date. ISO format YYYY-MM-DD (e.g. 2024-01-01). When omitted, no lower date bound is applied. |
| page_from | integer | Start page of a multi-page fetch range (0-based, inclusive). When provided with page_to, all pages in the range are fetched and merged. When provided alone, returns that single page. Overrides page when set. |
| price_result | boolean | When true, returns only lots with a non-zero price result value. When false (default), no priceResult filter is applied. |
| results_posted | boolean | When true, returns only lots where auction results have been posted. When false (default), no resultsPosted filter is applied. |
{
"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, supercategoryName, resultsPosted, priceResult, imageUrl, dateTimeUTCUnix",
"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 | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. 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.