Grail

3-year sold history

Deeper history than the recent sold window: historical eBay sold-market data returned as aggregate stats plus listing-level rows.

What it is

GET /v1/scrape returns individual sold listings from the recent window. GET /v1/research/sold is the deeper rail: it reaches back up to 3 years (1,095 days) and returns a keyword's market as historical sold-market data — average sold price, sold price range, total sold, sell-through, seller count and total item sales — plus the listing-level rows behind those numbers.

Request

GET /v1/research/sold?keyword=leica+m6&days=1095&count=50
Authorization: Bearer ***<key>
  • keyword — the search text (required).
  • days — history window in days, 1–1095 (default 365).
  • count — listing rows to return (1–50).
  • marketplace — ebay.com today.

Response

The envelope is stable (grail.research_sold.1). source.name is ebay_sold_history when this rail answers. coverage tells you exactly how deep and how complete the answer is.

{
  "schemaVersion": "grail.research_sold.1",
  "source": { "name": "ebay_sold_history", "kind": "sold_history" },
  "coverage": { "requestedDays": 1095, "itemsReturned": 50,
                "totalSold": 24491, "totalSellers": 5170 },
  "summary": { "mean": 367.63, "avgShipping": 17.6,
               "soldPriceRange": "$ 0.01 - $ 17,000.00",
               "freeShippingPct": 37.0, "totalItemSales": 9003626.33,
               "priceBasis": "sold_history_aggregate" },
  "items": [
    { "itemId": "275446905731", "title": "Leica M6 Classic 0.72 …",
      "url": "https://www.ebay.com/itm/275446905731",
      "soldPrice": 3100.00, "soldCurrency": "USD", "totalSold": 12,
      "sourceRowKind": "sold_history_listing_aggregate" }
  ]
}

Availability by plan

Every plan can reach the 3-year sold-history rail; the monthly allowance scales with your plan.

  • • Free — 10 history calls / month (a taste).
  • • Developer ($9) — 100 history calls / month.
  • • Pro ($29) and above — full 3-year sold history, bounded only by the plan allowance.

Over your plan's research allowance you get 402 upgrade_required — the call is not charged. Raise it by upgrading.

Honest limits

  • • Listing-level, not transaction-level. Each row is a listing aggregate over the window (what sold, how many, total sales), not one receipt per sale. Rows carry sourceRowKind: sold_history_listing_aggregate.
  • • Aggregate price basis. The summary comes from the historical sold-market aggregate; priceBasis is sold_history_aggregate. Median and per-row min/max are not derived from individual sales here.
  • • Accepted Best-Offer prices are not available on this rail; bestOfferAcceptedCount is null rather than guessed.
  • • Deep history is metered separately. One call to this rail is one request against your plan.

Which rail should I use?

  • • Recent, per-listing detail → GET /v1/scrape (up to 240 rows, recent window).
  • • Deep market context → GET /v1/research/sold (up to 3 years).
  • • Use both: history to size the market, scrape to price the item.