---
title: "Search Cards with Sorting"
method: POST
path: "/v1/cards/search-cards-wsort"
tags: ["Card Search"]
---

# Search Cards with Sorting

`POST /v1/cards/search-cards-wsort`

## Request

- Base URL: `https://api.cardhedger.com`
- URL: `https://api.cardhedger.com/v1/cards/search-cards-wsort`
- Auth: API key in header `X-API-Key`

Search for cards from the database with full-text search, filtering, sorting, and pagination.

**⚠️ Required:** At least one filter parameter (`search`, `set`, `category`, or `player`) is required.

**Search Parameter:**
- `search`: Full-text fuzzy search across card description and player names
- Supports multiple keywords: "Shohei Ohtani rookie" matches cards containing all terms

**Filter Parameters (exact match):**
- `player`: Exact player name match (e.g., "Mike Trout")
- `set`: Exact set name match (e.g., "2018 Panini Prizm Basketball")
- `category`: Exact category match (e.g., "Baseball", "Pokemon", "Basketball")

**Sorting Options:**
- `sort_by`:
  - `"gain"` - 7-day price change percentage
  - `"gain_30day"` - 30-day price change percentage
  - `"sales_7day"` - 7-day sales volume
  - `"sales_30day"` - 30-day sales volume
  - `"sales"` - alias for sales_30day (backwards compatible)
  - `"price"` - current price
  - `"description"` - alphabetical
- `sort_order`: "asc" or "desc"

**Other Options:**
- `raw_images_only`: When true, returns raw card images instead of graded slab images
- `page` / `page_size`: Pagination controls (max 100 per page)

**Response:**
- `pages`: Total pages available
- `count`: Total matching cards
- `cards`: Array of card objects including:
  - `gain`: 7-day price change percentage
  - `gain_30day`: 30-day price change percentage
  - `7 Day Sales` / `30 Day Sales`: Sales volume
  - `prices`: Array of grade/price pairs

## Request body

- CardSearchLocalRequest: Request parameters for the sortable card search endpoint.
  - `search` string, nullable: Full-text search query for fuzzy matching on card description/player (e.g., 'Trout rookie')
  - `set` string, nullable: Filter by exact set name (e.g., '2024 Topps Chrome Baseball')
  - `category` string, nullable: Filter by exact category (e.g., 'Baseball', 'Pokemon', 'Basketball')
  - `player` string, nullable: Filter by exact player name (e.g., 'Mike Trout', 'Shohei Ohtani')
  - `raw_images_only` boolean, nullable: Image preference. Omitted (default): return the raw card photo, falling back to the graded slab image only when no raw photo exists. true: force raw-only (no graded fallback). false: prefer the graded slab image.
  - `sort_by` 'gain' | 'gain_30day' | 'sales' | 'sales_7day' | 'sales_30day' | 'price' | 'description': Field to sort by: gain (7-day price change %), gain_30day (30-day price change %), sales_7day (7-day volume), sales_30day or sales (30-day volume), price (current price), description (alphabetical)
  - `sort_order` 'asc' | 'desc': Sort order: asc (ascending) or desc (descending)
  - `page` integer: Page number for pagination
  - `page_size` integer: Number of results per page (1-100)

## Response `200`

Successful Response

- CardSearchLocalResponse: Response model for local card search endpoint.
  - `pages` integer: Total number of pages available
  - `count` integer: Total number of matching cards
  - `cards` CardSearchLocalCard[]: 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', 'Gold', 'Refractor')
    - `card_id` string, required: Unique card identifier
    - `image` string, required: Card image URL
    - `category` string, required: Card category (e.g., 'Baseball', 'Pokemon')
    - `category_group` string, required: Category group (e.g., 'Sports Cards', 'Trading Cards')
    - `set_type` string, required: Set type
    - `7 Day Sales` integer, required: Sales volume in last 7 days
    - `30 Day Sales` integer, required: Sales volume in last 30 days
    - `rookie` boolean, required: Whether the card is a rookie card
    - `gain` number, required: Price gain percentage (7-day)
    - `gain_30day` number, required: Price gain percentage (30-day)
    - `stats_grade` string, required: Primary grade (e.g., 'PSA 10', 'BGS 9.5')
    - `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

## Other responses

- `422`: Validation Error

---

[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)