---
title: "Get Card Details by Auction ID"
method: POST
path: "/v1/cards/details-by-auction-id"
tags: ["Card Details"]
---

# Get Card Details by Auction ID

`POST /v1/cards/details-by-auction-id`

## Request

- Base URL: `https://api.cardhedger.com`
- URL: `https://api.cardhedger.com/v1/cards/details-by-auction-id`
- Auth: API key in header `X-API-Key`

Get card details for the sale with a marketplace auction ID.

For callers who hold a marketplace listing ID — an eBay item number, the
digits in `ebay.com/itm/<id>` — and want the card that sold.

## How it works

1. Finds the sale with this auction ID in Card Hedge price history.
2. If the sale is linked to a card, fetches that card.
3. Returns the same body as `/v1/cards/card-details`, plus a `sale` block
   describing the sale itself (grade, price, date, listing) and a
   `status` saying whether the card was found.

`sale.grade` is the grade of the item that sold, so the matching entry in
`cards[0].prices` is that grade's current price.

## Link status

Every recorded sale returns `200` with its `sale` block and a `status`:

- `linked` — the sale is linked to a card; `cards` holds it.
- `unlinked` — the sale is not linked to a card yet, so `cards` is empty
  and `sale.card_id` / `sale.grade` are null. Most sales from the last few
  hours are in this state. Sales are linked continuously, so a later call
  may return the card.
- `card_not_found` — the sale is linked (`sale.card_id`), but that card is
  missing from the catalog, so `cards` is empty.

## Status codes

- `404` `auction_not_found` — no sale with this auction ID.
- `502` — an upstream lookup failed.
- `503` — price-history search is temporarily unavailable.

**Example curl:**
```bash
curl -X POST -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{"auction_id": "407320981461"}' \
     "https://api.cardhedger.com/v1/cards/details-by-auction-id"
```

## Request body

- DetailsByAuctionIdRequest: Request parameters for the details-by-auction-id endpoint.
  - `auction_id` string, required: Marketplace listing ID of a sale: an eBay item number (the digits in `ebay.com/itm/<id>`). Matched exactly.

## Response `200`

Successful Response

- DetailsByAuctionIdResponse: The card-details body for the sale's card, plus the sale itself. ``cards`` is empty unless ``status`` is ``linked``.
  - `pages` integer: Total number of pages available
  - `count` integer: Total number of matching cards
  - `count_capped` boolean: True when `count` is a capped value and the real total is higher (filter-only browses cap the count for performance). Render as `count`+ — e.g. "10,000+".
  - `cards` CardSearchCard[], required: List of matching cards
    - `description` string, required: Full card description
    - `player` string, required: Player or character name
    - `set` string, required: Card set name
    - `number` string, required: Card number in set
    - `variant` string, required: Card variant (e.g., 'Base', 'Reverse Foil')
    - `card_id` string, required: Unique card identifier
    - `image` string, required: Card image URL
    - `category` string, required: Card category
    - `category_group` string, required: Category group
    - `set_type` string, required: Set type
    - `7 Day Sales` integer, required: Sales in last 7 days
    - `30 Day Sales` integer, required: Sales in last 30 days
    - `rookie` boolean, required: Whether the card is a rookie card
    - `gain` number, required: Price gain percentage
    - `prices` CardPrice[], required: Price information at different grades
      - `grade` string, required: Card grade (e.g., 'Raw', 'PSA 10')
      - `price` string, required: Price in string format
    - `subset` string, nullable: Card subset within the set (e.g. 'Base Set', 'Chrome'); null when the card has no subset
  - `status` 'linked' | 'unlinked' | 'card_not_found', required: `linked`: the sale is linked to a card, which `cards` holds. `unlinked`: the sale is not linked to a card yet, so `cards` is empty; sales are linked continuously, so a later call may return the card. `card_not_found`: the sale is linked (`sale.card_id`) but that card is missing from the catalog, so `cards` is empty.
  - `sale` AuctionSale, required: The sale an auction ID identifies, as recorded in Card Hedge price history.
    - `auction_id` string, required: Marketplace listing ID of the sale
    - `card_id` string, nullable: Card the sale is linked to; null while the sale is not linked to a card
    - `grade` string, nullable: Grade of the item sold (e.g. 'PSA 9', 'Raw'); null while the sale is not linked to a card
    - `price` number, required: Sale price in USD
    - `sale_date` string, nullable: Sale date and time (UTC, ISO 8601)
    - `sale_type` string, required: How it sold: Auction, Best Offer, BIN, or Sale
    - `price_source` string, required: Marketplace the sale came from (e.g. 'ebay')
    - `title` string, required: Listing title
    - `sale_url` string, required: Listing URL
    - `image` string, required: Listing image URL

## Other responses

- `404`: `auction_not_found`: no sale with this auction ID
- `422`: Validation Error
- `502`: An upstream lookup failed or was rejected
- `503`: Price-history search is unavailable or not configured

## Changes

- **2026-11-04** `6de42f192a4d`: 1 info
  - added the required property `status` to the response with the `200` status
- **2026-10-30** `b9c6b81e9d80`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cardhedger/apis/card-hedge-api/changes/v1/cards/details-by-auction-id/post.md)

---

[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.dev/cardhedger/apis/card-hedge-api/revisions/6de42f192a4d?raw)