sothebys.com APIsothebys.com ↗
Access Sotheby's auction metadata, lot details, estimates, provenance, and images via two structured endpoints. Covers auction sessions, lot cards, and creator info.
curl -X GET 'https://api.parse.bot/scraper/07b74ea0-86a6-4474-b947-6555a7edf5a4/get_auction_details?auction_id=%3Cauction_uuid%3E' \ -H 'X-API-Key: $PARSE_API_KEY'
Retrieve full details of a specific auction by its UUID. Returns auction metadata including title, location, dates, sessions, and a list of lots (lotCards) with their titles, creators, and UUIDs. Returns stale_input if the auction_id does not match an existing auction.
| Param | Type | Description |
|---|---|---|
| auction_idrequired | string | The UUID of the auction (e.g., 0abdc7da-6b95-4019-aaff-ecdd194f4bd9) |
{
"type": "object",
"fields": {
"slug": "object with name and year for URL construction",
"dates": "object — auction dates including acceptsBids and start times",
"title": "string — auction title",
"currency": "string — currency code (e.g. USD)",
"location": "object — location with name and displayLocation",
"lotCards": "array of lot summary objects with lotId, title, creatorsDisplayTitle, lotNumber, slug",
"overview": "string — HTML description of the auction",
"sessions": "array of session objects with sessionId, title, scheduledOpeningDate, lotRange",
"auctionId": "string — UUID of the auction"
},
"sample": {
"data": {
"slug": {
"name": "contemporary-day-sale",
"year": "2024"
},
"dates": {
"goesLive": "2024-11-21T15:00Z",
"__typename": "LiveAuctionDates",
"acceptsBids": "2024-11-04T17:00Z"
},
"title": "Contemporary Day Auction ",
"currency": "USD",
"location": {
"name": "New York",
"displayLocation": {
"name": "New York",
"timezone": "America/New_York"
}
},
"lotCards": [
{
"slug": {
"lotSlug": "taos"
},
"lotId": "9f85676c-96e5-497b-bc5e-92e69190bd13",
"title": "Taos",
"lotNumber": {
"lotDisplayNumber": "101"
},
"creatorsDisplayTitle": "Richard Mayhew"
}
],
"overview": "<p>...</p>",
"sessions": [
{
"title": "Session 1",
"lotRange": {
"toLotNr": 255,
"fromLotNr": 101
},
"sessionId": 0,
"scheduledOpeningDate": "2024-11-21T15:00Z"
}
],
"auctionId": "0abdc7da-6b95-4019-aaff-ecdd194f4bd9"
},
"status": "success"
}
}About the sothebys.com API
The Sotheby's API exposes two endpoints — get_auction_details and get_lot_details — covering auction metadata and individual lot records from sothebys.com. A single auction response returns over 8 distinct fields including session schedules, lot card arrays, currency, and location. Lot responses add estimate ranges, high-resolution image renditions, HTML provenance descriptions, and parent auction context, making it practical to reconstruct auction records or track individual works.
Auction Data
The get_auction_details endpoint accepts a UUID via the auction_id parameter and returns a full auction record. The response includes the auction title, currency, location object (with name and displayLocation), and a dates object covering bid acceptance and session start times. The sessions array breaks multi-session sales into individual records with scheduledOpeningDate and lotRange, useful when an auction spans multiple days or categories. The lotCards array provides a pageable summary of every lot in the auction, each with lotId, lotNumber, title, creatorsDisplayTitle, and a slug for URL construction.
Lot Data
get_lot_details takes both a lot_id and auction_id UUID — the lot UUID can be pulled from the lotCards array returned by get_auction_details. The response contains the lot title, description (HTML), creatorsDisplayTitle, and a media object with an images array that includes multiple renditions at different sizes. Estimate data lives in estimateV2, which surfaces lowEstimate and highEstimate amounts or an estimateUponRequest flag when no public figure is available. The nested auction object repeats key parent fields like currency, locationV2, and slug so lot records are self-contained.
Error Behavior and IDs
Both endpoints return a stale_input status when the supplied UUID does not match an existing record. Auction and lot UUIDs are not sequential integers — they are full UUIDs (e.g., 0abdc7da-6b95-4019-aaff-ecdd194f4bd9) and must be obtained from a prior get_auction_details call or known in advance. There is no search or listing endpoint in this API; coverage depends on knowing valid auction UUIDs as entry points.
- Build an art valuation tool that pulls
estimateV2low/high figures across lots by a given creator - Aggregate auction session schedules from the
sessionsarray to track upcoming Sotheby's sale dates - Compile a lot image archive using the
media.imagesrenditions array fromget_lot_details - Research provenance and ownership history using the HTML
descriptionfield returned per lot - Map auction geography by extracting
location.displayLocationacross multiple auction records - Index lot-level creator attribution via
creatorsDisplayTitleto build an artist sales database - Cross-reference parent auction currency and title from the lot's nested
auctionobject for multi-currency sales analysis
| 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 | 250 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 Sotheby's have an official developer API?+
What does get_lot_details return for estimates when Sotheby's doesn't publish a public figure?+
estimateV2 object includes an estimateUponRequest flag for lots where no public estimate is listed. When a public estimate exists, lowEstimate and highEstimate amounts are returned in the auction's currency.Does the API return hammer prices or realized sale results?+
Is there a way to search or browse auctions without knowing a UUID first?+
auction_id for get_auction_details and both lot_id and auction_id for get_lot_details. There is no search or browse endpoint that accepts keywords or filters. You can fork this API on Parse and revise it to add a search or listing endpoint to discover auction UUIDs programmatically.Does the lot response include condition reports or exhibition history?+
description field returns an HTML block that may contain provenance narrative, but structured condition reports and exhibition history are not broken out as discrete fields in the current response schema. You can fork this API on Parse and revise it to surface those fields if they are available on individual lot pages.