Ha APIsports.ha.com ↗
Access sold sports collectible lot data from Heritage Auctions. Search archived sales, retrieve lot titles, sale numbers, grades, and images via 2 endpoints.
What is the Ha API?
The Heritage Auctions Sports API provides structured data from the sports.ha.com sold-lot archive across 2 endpoints. Use search_sales to query archived lots by keyword — player name, card set, or grading company — and get_lot to retrieve full detail for any individual lot, including parsed grade, grader, certification link, and primary image URL.
curl -X GET 'https://api.parse.bot/scraper/e6c3bd2e-d08d-490e-914f-e9162e7db64a/search_sales?limit=2&query=michael+jordan+psa' \ -H 'X-API-Key: $PARSE_API_KEY'
Searches Heritage Auctions' sports Auction Archives restricted to the site's 'Archive: Sold' filter and returns up to 5 sold lots per call in the site's Best Match order. Each row carries the original lot title, the lot page URL, the sale and lot numbers plus Heritage's internal lot object id, sale_status 'sold' (sourced from the site filter), the auction's end date as shown on the result list (auction_ended_date, day precision; this is the auction close, not necessarily the lot's own sale day - use get_lot for that), the price label as displayed, and grader/grade parsed from the title. price_amount, currency and buyer-premium fields are null because Heritage hides realized prices from anonymous visitors (price_access = 'requires_sign_in'). Pagination is caller-driven: page (default 1) with page size limit (default 5, max 5); has_more tells whether a further page exists. A query with no sold matches returns an empty results array. One or two site requests per call.
| Param | Type | Description |
|---|---|---|
| page | integer | 1-based page index over pages of `limit` lots. |
| limit | integer | Number of lots per page, 1 to 5. Values outside that range are rejected. |
| queryrequired | string | Free-text keyword search matched against lot titles and descriptions (e.g. player name, set, grader). |
{
"type": "object",
"fields": {
"page": "page index served",
"limit": "page size served",
"query": "echo of the search term",
"source": "description of the site section and filter used",
"results": "array of sold-lot summaries (title, lot_url, lot_key 'saleNo-lotNo', sale_no, lot_no, lot_id_no, sale_status, status_source, auction_ended_date YYYY-MM-DD, sale_date/sale_date_precision always null on this endpoint, price_amount null, price_label, price_access, currency null, buyers_premium_included null, buyers_premium_rate_pct null, grader, grade, categories, highlights, image_url)",
"has_more": "true when another page of results exists",
"price_note": "why price amounts are null"
},
"sample": {
"data": {
"page": 1,
"limit": 5,
"query": "michael jordan psa",
"source": "Heritage Auctions Sports (sports.ha.com), Auction Archives, filter Archive: Sold",
"results": [
{
"grade": "Gem Mint 10",
"title": "1985 Nike Promo Michael Jordan PSA Gem Mint 10",
"grader": "PSA",
"lot_no": "57169",
"lot_key": "60004-57169",
"lot_url": "https://sports.ha.com/itm/basketball-cards/singles-1980-now-/1985-nike-promo-michael-jordan-psa-gem-mint-10/a/60004-57169.s",
"sale_no": "60004",
"currency": null,
"image_url": "https://dyn1.heritagestatic.com/ha?p=2-3-7-7-4-23774114&it=product",
"lot_id_no": "125001",
"sale_date": null,
"categories": [
"Basketball",
"1970 and later"
],
"highlights": [],
"price_label": "Sold For",
"sale_status": "sold",
"price_access": "requires_sign_in",
"price_amount": null,
"status_source": "Site filter 'Archive: Sold' (result list shows 'Sold For')",
"auction_ended_date": "2021-04-15",
"sale_date_precision": null,
"buyers_premium_included": null,
"buyers_premium_rate_pct": null
}
],
"has_more": true,
"price_note": "Heritage shows realized prices only to signed-in users; amounts are null on public pages."
},
"status": "success"
}
}About the Ha API
What the API Returns
The API covers Heritage Auctions' sports collectibles archive, specifically lots marked as sold. search_sales accepts a required query string (e.g. "Mickey Mantle PSA 9" or "1952 Topps BGS") and returns up to 5 matching lots per call, ordered by Heritage's Best Match ranking. Each result includes the lot title, a canonical lot_url, a composite lot_key in saleNo-lotNo format, the individual sale_no, lot_no, and lot_id_no, plus a sale_status field and the price_note explaining why realized prices are always null. Pagination is controlled with page and limit parameters (limit capped at 5), and has_more tells you whether another page exists.
Lot Detail Fields
get_lot takes a url — either from search_sales results or any *.ha.com/itm/ or /c/item.zx lot link — and returns the complete set of public page fields: title, sale_no, lot_no, lot_key, lot_url, image_url, grade (parsed from the title string), grader (e.g. PSA, BGS, SGC), cert_url (a direct PSA registry link when present), and sale_status. Both currency and realized price are always null because Heritage restricts price data to signed-in users on the public-facing archive pages.
Limitations to Know
Realized prices are not available — this is a Heritage site policy on public archive pages, not a gap in the endpoint. The grade and grader fields are parsed from the lot title text, so lots with non-standard title formatting may return null for those fields even when a grade exists. Search results are capped at 5 lots per call and follow Heritage's own Best Match ordering; there is no way to sort by sale date, lot number, or sale number through this API.
The Ha API is a managed, monitored endpoint for sports.ha.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when sports.ha.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 sports.ha.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?+
- Build a price-history reference tool that tracks which grades and sets have appeared at Heritage auction using title and lot metadata
- Aggregate PSA cert numbers from cert_url fields to cross-reference cards that have passed through Heritage with registry data
- Track how frequently specific player and set combinations appear in Heritage's sold archive using search_sales keyword queries
- Populate a sports card research database with Heritage lot titles, sale numbers, and image URLs for cataloging purposes
- Monitor Heritage archive coverage for a specific grader (PSA, BGS, SGC) by querying search_sales with grader name as keyword
- Extract lot_key identifiers for a set of auctions to build a structured index of Heritage sports lots by sale number
| 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 Heritage Auctions offer an official developer API?+
Why are realized prices always null in the responses?+
price_note field in both endpoints explains this. Every other lot fact available on the public archive pages — title, lot numbers, grade, grader, cert link, image — is returned normally.Does the API cover upcoming or live Heritage sports auctions, not just sold lots?+
Can I retrieve all lots from a specific Heritage sale number?+
search_sales filters by keyword query, not by sale number, and returns results in Heritage's Best Match order with a maximum of 5 per call. You can include a sale number as part of your search query, but targeted retrieval of all lots within a single sale is not a built-in filter. You can fork this API on Parse and revise it to add a sale-number browsing endpoint.How reliable are the parsed grade and grader fields?+
grade and grader fields in get_lot are parsed from the lot title string. Lots where the title follows Heritage's standard naming conventions will return accurate values. Lots with non-standard or abbreviated title formatting may return null for one or both fields even when grading information is present in the full title text.