---
title: "Get Paginated Comparable Sales by Certificate Number"
method: POST
path: "/v1/cards/comps-by-cert"
tags: ["Pricing & Valuations"]
---

# Get Paginated Comparable Sales by Certificate Number

`POST /v1/cards/comps-by-cert`

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**

| Input | Grade queried |
|---|---|
| omitted, null, or blank | Grade recorded on the certificate |
| ``"9"`` on a PSA certificate | ``PSA 9`` |
| ``"PSA 9"`` | ``PSA 9`` |
| ``"Raw"`` | ``Raw`` (never ``PSA Raw``) |
| ``"AUTH"`` on a PSA certificate | ``PSA 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**

```bash
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**

```bash
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"
    }
  }'
```

## Request body

- CertCompsRequest — Resolve a graded certificate and return paginated comparable sales.
  - `cert_number` string, required — Certificate number issued by grading_company. Send it as a string so any leading zeroes are preserved.
  - `grading_company` string, 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.
  - `grade` string, 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.
  - `limit` integer — Maximum sales records to return on this page (1-100; default 20)
  - `offset` integer — Zero-based starting position in the matching sales. For the next page, add count_returned to the current offset.
  - `date_range` CertCompsDateRange — Inclusive UTC sale-date range for cert-to-comps queries.
    - `start_date` string, date, required — First sale date to include, inclusive, in YYYY-MM-DD format
    - `end_date` string, date, required — Last sale date to include, inclusive, in YYYY-MM-DD format

## Response `200`

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

- CertCompsResponse — Certificate metadata, card match, comp summary, and raw paginated sales.
  - `cert_info` GemRateCertInfo, required — Certificate verification information.
    - `grader` string, required — Grading company (e.g., PSA, BGS, CGC)
    - `cert` string, required — Certificate number
    - `grade` string, required — Card grade (e.g., PSA 10, BGS 9.5)
    - `gemrate_id` string, nullable — Unique card identifier
    - `universal_gemrate_id` string, nullable — Universal card identifier
    - `description` string, nullable — Card description from certificate
  - `card` CardDetails — Detailed card information and metadata.
    - `card_id` string, required — Unique card identifier
    - `description` string, nullable — Full card description
    - `player` string, nullable — Player or character name
    - `set` string, nullable — Card set name
    - `number` string, nullable — Card number in set
    - `variant` string, nullable — Card variant (e.g., Base, Refractor, Prizm)
    - `image` string, nullable — Card image URL
    - `category` string, nullable — Card category (e.g., Baseball, Basketball, Pokemon)
    - `category_group` string, nullable — Category group
    - `set_type` string, nullable — Set type
  - `card_source` string, 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_confidence` number, nullable — AI card-match confidence from 0 to 1 when card_source is card_match; otherwise null
  - `grade_used` string, required — Canonical grade actually used to query comparable sales
  - `date_range` CertCompsDateRange — Inclusive UTC sale-date range for cert-to-comps queries.
    - `start_date` string, date, required — First sale date to include, inclusive, in YYYY-MM-DD format
    - `end_date` string, date, required — Last sale date to include, inclusive, in YYYY-MM-DD format
  - `total_count` integer, 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
  - `limit` integer, required — Requested maximum page size
  - `offset` integer, required — Requested zero-based starting position
  - `count_returned` integer, required — Raw sales returned on this page
  - `has_more` boolean, required — Whether another page is available. When true, request the next page with offset + count_returned.
  - `comp_price` number, nullable — Average comparable price after IQR anomaly filtering on this page only; null when the page has no sales
  - `high` number, nullable — Highest sale used in this page's comp calculation
  - `low` number, nullable — Lowest sale used in this page's comp calculation
  - `raw_high` number, nullable — Highest unfiltered sale in this response page; null when the page has no sales
  - `raw_low` number, nullable — Lowest unfiltered sale in this response page; null when the page has no sales
  - `count_requested` integer, required — Requested number of sales; retained for compatibility and equal to limit
  - `count_used` integer, required — Sales used in this page's comp calculation after anomaly filtering
  - `time_weighted` boolean — Always false; this page-level comp calculation is not time-weighted
  - `sales` CertCompSale[] — Unfiltered raw sales. Statistical outliers remain present even when they are excluded from the page-level comp calculation. Rows are sorted by sale_date newest-first, and that ordering holds across page boundaries.
    - `sale_date` string, nullable — Authoritative sale timestamp in ISO 8601 format
    - `price` number, required — Sale price in USD
    - `grade` string, required — Canonical grade used for the comparable-sales query
    - `grader` string, required — Canonical grader derived from grade; Raw sales use Raw
    - `price_source` string, nullable — Marketplace or source that supplied the sale
    - `sale_type` string, nullable — Sale type, such as Auction or Best Offer
    - `sale_url` string, nullable — Direct link to the sold listing when available
    - `image` string, nullable — Card or sale-listing image URL when available
    - `card_id` string, nullable — Resolved CardHedge card ID
    - `price_history_id` string, nullable — CardHedge sale record ID
    - `title` string, nullable — Sale listing title

## Other responses

- `400` — The requested grade is not available
- `404` — The certificate was not found
- `422` — Validation Error
- `502` — A required upstream provider failed after retries

---

[API](https://skmtc.dev/cardhedger/apis/card-hedge-api.md) · [All operations](https://skmtc.dev/cardhedger/apis/card-hedge-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cardhedger/card-hedge-api/revisions/f2d0e595be79/schema)