Sothebys APIsothebys.com ↗
Access Sotheby's auction metadata, lot details, estimates, images, and provenance via 2 endpoints. Retrieve auction sessions, lot lists, and creator info.
What is the Sothebys API?
The Sotheby's API exposes 2 endpoints covering auction metadata and individual lot details from sothebys.com. Use get_auction_details to retrieve session schedules, lot listings, and location data for any auction by UUID, or use get_lot_details to pull estimate ranges, provenance, images, and creator attribution for a specific lot. Both endpoints return structured JSON ready for art valuation research, collection tracking, and market analysis.
curl -X GET 'https://api.parse.bot/scraper/07b74ea0-86a6-4474-b947-6555a7edf5a4/get_auction_details?auction_id=0abdc7da-6b95-4019-aaff-ecdd194f4bd9' \ -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 sothebys-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.
from parse_apis.sothebys_auction_api import Sothebys, Auction, Lot, ItemNotFound
sothebys = Sothebys()
# Fetch auction details by UUID
auction = sothebys.auctions.get(auction_id="0abdc7da-6b95-4019-aaff-ecdd194f4bd9")
print(auction.title, auction.currency)
print(auction.location.name)
print(auction.dates.accepts_bids, auction.dates.goes_live)
# Browse sessions
for session in auction.sessions:
print(session.title, session.scheduled_opening_date)
if session.lot_range:
print(session.lot_range.from_lot_nr, session.lot_range.to_lot_nr)
# Browse lot cards from the auction
for card in auction.lot_cards:
print(card.lot_id, card.title, card.creators_display_title)
# Drill into a specific lot for full details
lot = auction.lots.get(lot_id=auction.lot_cards[0].lot_id)
print(lot.title, lot.description)
print(lot.creators_display_title)
if lot.estimate:
if lot.estimate.estimate_upon_request:
print("Estimate upon request")
elif lot.estimate.low_estimate and lot.estimate.high_estimate:
print(lot.estimate.low_estimate.amount, lot.estimate.high_estimate.amount)
if lot.media:
for image in lot.media.images:
for rendition in image.renditions:
print(rendition.url, rendition.image_size, rendition.width, rendition.height)
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.
| 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 with auction timing info (acceptsBids, goesLive or startsToClose)",
"title": "string auction title",
"currency": "string currency code (e.g. USD)",
"location": "object with name and displayLocation sub-object",
"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 API
Auction Data via get_auction_details
The get_auction_details endpoint accepts a single required parameter, auction_id (a UUID string such as 0abdc7da-6b95-4019-aaff-ecdd194f4bd9), and returns a full auction record. The response includes the auction title, currency, location object (with name and displayLocation), and a dates object that surfaces timing fields like acceptsBids and goesLive. The sessions array breaks the auction into discrete sale sessions, each with a sessionId, scheduledOpeningDate, and lotRange. The lotCards array provides a pageable summary of every lot in the auction, with each entry carrying lotId, lotNumber, title, creatorsDisplayTitle, and slug — the fields you need to feed into the lot detail endpoint.
Lot Data via get_lot_details
The get_lot_details endpoint requires both lot_id and auction_id UUIDs. It returns a detailed lot record including title, creatorsDisplayTitle, description (HTML string or null), and estimateV2 — an object that contains either lowEstimate/highEstimate monetary amounts or an estimateUponRequest flag. The media object holds an images array with multiple renditions at different sizes, suitable for display or archiving. Parent auction context is embedded in the auction sub-object, giving you auctionId, title, currency, slug, and locationV2 without a second lookup.
Coverage and Identifiers
Both endpoints are keyed on Sotheby's internal UUID format. Auction UUIDs and lot UUIDs are stable identifiers — lot UUIDs appear in the lotCards array returned by get_auction_details, so the typical workflow is to fetch an auction first, collect lotId values from lotCards, then query each lot individually. The slug fields on both auctions and lots correspond to the URL path structure on sothebys.com and can be used to construct canonical links.
The Sothebys API is a managed, monitored endpoint for sothebys.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when sothebys.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 sothebys.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 hammer estimates and sale results for a specific artist by collecting
estimateV2data across multiple auctions. - Build an auction calendar app using
sessions[*].scheduledOpeningDateanddates.goesLivefields. - Archive lot images at multiple resolutions using the
media.imagesrenditions array fromget_lot_details. - Research provenance and collection history using the
descriptionHTML field returned per lot. - Aggregate lot counts per auction by measuring the
lotCardsarray length fromget_auction_details. - Map auction geography using
location.displayLocationandlocationV2fields across multiple auction records. - Cross-reference creator names via
creatorsDisplayTitleto compile sales histories for individual artists.
| 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 Sotheby's offer an official public developer API?+
What does get_lot_details return for estimate information?+
estimateV2 object contains either a lowEstimate and highEstimate pair (monetary amounts in the auction's currency) or an estimateUponRequest flag when Sotheby's has not published a numeric range for that lot. Realized sale prices are not included in the current response shape.Does the API return sold/realized prices for lots?+
estimateV2, lot metadata, images, and provenance descriptions. Realized hammer prices and buyer's premium totals are not fields in the current response. You can fork this API on Parse and revise it to add a realized-price endpoint if that data becomes accessible.Is there pagination for the lotCards array in get_auction_details?+
lotCards array is returned as part of the single get_auction_details response for a given auction_id. Large auctions with many lots may return a truncated list — there is no built-in pagination parameter exposed in the current endpoint. You can fork the API on Parse and revise it to add offset or page-based parameters for large auction lots.What data is required to call get_lot_details, and where do I get it?+
lot_id and auction_id are required UUID strings. The intended workflow is to call get_auction_details first with a known auction_id, then extract lotCards[*].lotId values from the response to use as inputs to get_lot_details.