Sign in
Pricing & Valuations

Get Paginated Comparable Sales by Certificate Number

Resolve a grading certificate and return raw comparable sales.

Resolve cert_number through GemRate, match the certificate to a CardHedge card, and return one page of raw sales plus an exact matching total_count.

Grade overrides

InputGrade queried
omitted, null, or blankGrade recorded on the certificate
"9" on a PSA certificatePSA 9
"PSA 9"PSA 9
"Raw"Raw (never PSA Raw)
"AUTH" on a PSA certificatePSA AUTH
"CGC AUTH"CGC AUTH

Auth and Authentic are accepted aliases for AUTH. An explicit full grade label can target a different grader than the certificate.

Pagination

  • limit is the maximum page size (1-100; default 20).
  • offset is a zero-based record position.
  • total_count covers every matching sale, not only this page.
  • When has_more is true, request the next page with offset + count_returned.
  • offset + limit cannot exceed 10000. Narrow the result set with date_range to reach sales beyond that depth.

Dates and ordering

date_range filters the authoritative sale date using inclusive UTC calendar dates. When omitted, the endpoint selects the most recent matching sales. Records are sorted by sale_date newest-first, and that ordering holds across page boundaries.

Sales recorded from 2020-07-01 onward are covered, so total_count on a vintage card counts sales from that date rather than all time.

Comp summary and raw records

Every source row remains in sales. The page-level comp_price, high, low, and count_used use the same IQR anomaly filtering as /comps, but that calculation never removes records from sales and applies only to the current page. raw_high and raw_low report the unfiltered extrema from every sale in the current page.

Example curl: Raw override

curl -X POST "https://api.cardhedger.com/v1/cards/comps-by-cert" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cert_number": "134669109",
    "grading_company": "PSA",
    "grade": "Raw",
    "limit": 20,
    "offset": 0
  }'

Example curl: inclusive Sale Date range

curl -X POST "https://api.cardhedger.com/v1/cards/comps-by-cert" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cert_number": "134669109",
    "grading_company": "PSA",
    "grade": "PSA 9",
    "limit": 20,
    "offset": 0,
    "date_range": {
      "start_date": "2026-01-01",
      "end_date": "2026-06-30"
    }
  }'
post/v1/cards/comps-by-cert

Request body

cert_numberstring required

Certificate number issued by grading_company. Send it as a string so any leading zeroes are preserved.

grading_companystring required

Company that issued the certificate, such as PSA, BGS, SGC, or CGC. This identifies the certificate; it does not force an explicit full grade override to use the same grader.

gradestring nullable

Grade to query, such as 'PSA 10', '10', 'Raw', or 'PSA AUTH'. Bare numeric and AUTH values inherit the certificate's grading company. Raw is always grader-independent. Blank or omitted uses the grade recorded on the certificate.

limitinteger

Maximum sales records to return on this page (1-100; default 20)

offsetinteger

Zero-based starting position in the matching sales. For the next page, add count_returned to the current offset.

Example request

{
  "cert_number": "134669109",
  "grading_company": "PSA",
  "limit": 20,
  "offset": 0
}

Response

Resolved certificate, matched card, pagination metadata, and raw sales

card_sourcestring nullable

Card resolution source: gemrate_id for a direct ID match, card_match for an AI description match, or null when no card was resolved

match_confidencenumber nullable

AI card-match confidence from 0 to 1 when card_source is card_match; otherwise null

grade_usedstring required

Canonical grade actually used to query comparable sales

total_countinteger required

Exact total raw sales matching the resolved card, grade, and optional date range across all pages, counting sales recorded from 2020-07-01 onward

limitinteger required

Requested maximum page size

offsetinteger required

Requested zero-based starting position

count_returnedinteger required

Raw sales returned on this page

has_moreboolean required

Whether another page is available. When true, request the next page with offset + count_returned.

comp_pricenumber nullable

Average comparable price after IQR anomaly filtering on this page only; null when the page has no sales

highnumber nullable

Highest sale used in this page's comp calculation

lownumber nullable

Lowest sale used in this page's comp calculation

raw_highnumber nullable

Highest unfiltered sale in this response page; null when the page has no sales

raw_lownumber nullable

Lowest unfiltered sale in this response page; null when the page has no sales

count_requestedinteger required

Requested number of sales; retained for compatibility and equal to limit

count_usedinteger required

Sales used in this page's comp calculation after anomaly filtering

time_weightedboolean

Always false; this page-level comp calculation is not time-weighted

Example response

{
  "grade_used": "PSA 9",
  "date_range": {
    "start_date": "2026-01-01",
    "end_date": "2026-06-30"
  },
  "sales": [
    {
      "sale_date": "2026-06-30T12:00:00.000Z",
      "grade": "PSA 9",
      "grader": "PSA",
      "price_source": "ebay"
    }
  ]
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.