Market Data

Get Sales Trends by Category (Matched Sales Only)

Changed on

Matched sales only. A matched sale is a sale Card Hedge has linked to a specific card in its catalog. This endpoint includes only matched sales whose linked card has a known category. Unmatched sales are excluded from every count, total amount, and average price. These statistics do not represent all marketplace sales in a category.

Return daily, weekly, or monthly sale counts, total amounts (USD), and average sale prices grouped by the linked card's category. Category names match exactly, ignoring case and surrounding whitespace. A category word appearing in a sale title does not qualify that sale for inclusion.

A zero count means no qualifying matched sales were found for the category and period; it does not mean no marketplace sales occurred. Unknown categories also return zero statistics.

Like sales-stats-by-player, buckets are UTC calendar days, ISO weeks (Monday–Sunday), or months, ordered oldest to newest. periods includes the current partial bucket when include_current is true. The response's scope: matched_only distinguishes these statistics from all-market sales.

Completed buckets are cached for 24 hours; the current partial bucket for 5 minutes. Day and period boundaries use separate cache keys. Results reflect indexed card links and may lag changes by the cache TTL. Redis failures fall back to querying OpenSearch. Limits: 25 categories, day ≤ 90 / week ≤ 52 / month ≤ 24 periods, and 150 total buckets.

post/v1/cards/sales-stats-by-category

Request

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

Request body

categoriesstring[] required

Exact linked-card category names (case-insensitive), in response order (max 25). Only matched sales with a known card category are counted.

interval'day' | 'week' | 'month'

UTC calendar buckets: day, ISO week (Monday–Sunday), or month.

periodsinteger

Buckets per category, including the current period when requested. Caps: day ≤ 90, week ≤ 52, month ≤ 24; categories × periods ≤ 150.

include_currentboolean

Include the in-progress period as the newest, partial bucket.

Response

Successful Response

scope'matched_only'

Always matched_only: includes only sales Card Hedge has linked to catalog cards with a known category. Unmatched sales are excluded from all statistics; these are not all-marketplace totals.

interval'day' | 'week' | 'month' required
periodsinteger required

Number of buckets returned per category.

Changes