Pricing & Valuations

Get Newest Clean Sales by Text Search and Grade (Commercial Agreement Required)

Changed on Sep 12, 2026

Return the newest N clean sales for a text-described card and grade.

Commercial access is required. The authenticated API accepts Enterprise tier keys; paid calls use the Agent API adapter for this same handler.

Sports queries require a release year (including seasons such as 2023-24) before retrieval. Non-sports queries do not require a year. Category and clear sports product/category words establish whether this rule applies; ambiguous uncategorized text is not assumed to be sports. TCG queries require a card number, such as #4, 4/102, or OP01-001. A year, grade, set code or explicitly labeled serial is not a card number. sales-by-search is not a general free-text search. Use card identifiers to specify one card: player/character, set/product, card number and variant where applicable. Put the grade in the grade field. A catalog card_id is not required.

The public contract deliberately has no date range. last_n is filled after filtering: the service keeps scanning newest-first index pages until N sales survive, the index is exhausted, or the configured safety limit is reached.

Text retrieval runs concurrently with optional, budgeted card-match enrichment. A match must validate against the original query before its header or exact card-ID stream is used. Timeouts and rejected matches fall back to an inferred header. Inspect results.coverage_complete and partial_reasons for deadline, unresolved-listing, and identity ambiguity.

post/v1/cards/sales-by-search

Request

Base URL
https://api.cardhedger.com
Auth
API key in header X-API-Key

Request body

querystring required

sales-by-search is not a general free-text search. Use card identifiers to specify one card: player/character, set/product, card number and variant where applicable. Put the grade in the grade field. The card does not need to exist in the Card Hedge catalog. Sports searches require a four-digit release year or season, such as 2025 or 2023-24. Non-sports searches do not require a year. TCG searches require a card number, such as #4, 4/102, or OP01-001.

gradestring required

Exact grade to return, such as PSA 10, BGS 9.5, or Raw.

last_ninteger nullable

Number of newest matching sales to return. This operation is available only to Enterprise API keys and paid Agent API calls; eligible callers may request 1-20. When omitted, it defaults to 10.

categorystring nullable

Optional card category used by card-match, such as Basketball or Pokemon. Supply this when the text does not clearly identify sports versus non-sports; non-sports searches do not require a year. Listed TCG names, including Pokemon, Lorcana and Yu-Gi-Oh, require a card number. Names are matched case-insensitively, including documented accent, spacing and hyphen variants.

Example request

{
  "query": "2018 Panini Prizm Luka Doncic #280 Silver",
  "grade": "PSA 10"
}

Response

Curated card header when card-match succeeds, plus the newest sales that survive grade and sibling-variant filtering

querystring required

search_query_usedstring required

Primary cleaned index query; the original query is also searched when cleaning changed it. When both retrieve too few sales, one broader query (subject and card number) is also searched.

gradestring required

Example response

{
  "exclusions": {
    "duplicate": 0,
    "sibling_variant": 2,
    "uncertain": 0,
    "wrong_card": 0,
    "wrong_grade": 3,
    "wrong_item": 0
  },
  "grade": "PSA 10",
  "header": {
    "card": {
      "card_id": "1587446850514x224832321163624450",
      "category": "Basketball",
      "confidence": 0.95,
      "description": "Luka Doncic 2018 Panini Prizm Basketball Silver",
      "image": "https://images.example.com/luka-280.jpg",
      "number": "280",
      "player": "Luka Doncic",
      "prices": [
        {
          "grade": "PSA 10",
          "price": "1200"
        }
      ],
      "reasoning": "Exact player, set, number, and variant match.",
      "set": "2018 Panini Prizm Basketball",
      "subset": "Base Set",
      "variant": "Silver"
    },
    "card_match_status": "matched",
    "source": "curated_card"
  },
  "query": "2018 Panini Prizm Luka Doncic #280 Silver",
  "results": {
    "candidates_scanned": 7,
    "classifier_mode": "enforce",
    "complete": true,
    "index_exhausted": false,
    "requested": 2,
    "returned": 2,
    "scan_limit_reached": false
  },
  "sales": [
    {
      "card_id": "1587446850514x224832321163624450",
      "grade": "PSA 10",
      "grader": "PSA",
      "id": "sale-1",
      "image": "https://i.ebayimg.com/example.jpg",
      "match_method": "curated_id",
      "price": 1150,
      "price_source": "ebay",
      "sale_date": "2026-08-29T19:30:00.000Z",
      "sale_type": "Auction",
      "sale_url": "https://www.ebay.com/itm/example",
      "title": "2018 Prizm Luka Doncic #280 Silver PSA 10"
    }
  ],
  "search_query_used": "2018 Panini Prizm Luka Doncic #280 Silver"
}

Changes

Sep 12, 202650d06a3a1edc Revision changes
- info
  added the non-success response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status

Operation history