---
title: "Get Sales Trends by Player (Daily/Weekly/Monthly)"
method: POST
path: "/v1/cards/sales-stats-by-player"
tags: ["Market Data"]
---

# Get Sales Trends by Player (Daily/Weekly/Monthly)

`POST /v1/cards/sales-stats-by-player`

## Request

- Base URL: `https://api.cardhedger.com`
- URL: `https://api.cardhedger.com/v1/cards/sales-stats-by-player`
- Auth: API key in header `X-API-Key`

Return sales statistics per player — **count**, **total amount (USD)**, and
**mean sale price** — bucketed by day, week, or calendar month. Useful for
trend charts, period-over-period comparisons, and tracking how a player's
market is moving over time.

### How buckets are aligned

All buckets are calendar-aligned in UTC:

- **`day`** — midnight-to-midnight UTC.
- **`week`** — ISO week, Monday → Sunday.
- **`month`** — first → last calendar day of the month.

### Current (in-progress) period

By default (`include_current: true`) the newest bucket is the in-progress
period (month-to-date, week-to-date, or today so far) and is flagged with
`partial: true` so clients can render it differently — e.g. a dashed line
on a chart. Set `include_current: false` to return only fully-closed
periods, which is the right choice for clean trend lines.

The `periods` value is the **total** number of buckets returned, regardless
of whether the newest is partial. Requesting `periods=12, interval=week`
with the default flag returns 11 closed weeks + 1 partial (week-to-date).

### Caps and rate considerations

`periods` is capped per interval to keep request fan-out reasonable:

| Interval | Max periods |
|----------|-------------|
| `day`    | 90          |
| `week`   | 52          |
| `month`  | 24          |

Closed buckets are cached server-side for 24 hours, so repeat calls for
the same player/interval are near-instant. The partial bucket is never
cached and is recomputed on every request.

### Field meanings

- `count` — number of sales matching the player name in the bucket window.
- `total_amount` — sum of sale prices in USD.
- `average_sale` — arithmetic mean (sum ÷ count). Note that the underlying
  data includes some very low-value sales (e.g. bulk lots), which can pull
  the mean down for high-volume players.
- `partial` — `true` only for the in-progress current bucket.

Buckets are returned **oldest → newest**.

## Request body

- SalesStatsByPlayerRequest
  - `players` string[], required: Player or character names to look up. Each name is matched against the sale description text. Up to 25 names per request.
  - `interval` 'day' | 'week' | 'month': Bucket size. `day` = midnight-to-midnight UTC, `week` = ISO week (Monday → Sunday), `month` = calendar month (1st → last day).
  - `periods` integer: Total number of buckets to return, ending with the most recent period. When `include_current` is true (default) the newest bucket is the in-progress period and counts toward this total. Caps per interval: day ≤ 90, week ≤ 52, month ≤ 24.
  - `include_current` boolean: When true (default), the newest bucket is the in-progress current period (month-to-date, week-to-date, or today so far) and is flagged `partial: true`. Set false to return only fully-closed periods — preferred for clean trend charts.

## Response `200`

Successful Response

- SalesStatsByPlayerResponse
  - `interval` 'day' | 'week' | 'month', required: Bucket size used for this response.
  - `periods` integer, required: Number of buckets returned per player (matches the request).
  - `results` PlayerSalesStats[], required: One entry per requested player, in request order.
    - `player` string, required: Player or character name searched.
    - `buckets` SalesStatsBucket[], required: Buckets ordered oldest to newest.
      - `start` string, required: Bucket start date in UTC, inclusive (YYYY-MM-DD).
      - `end` string, required: Bucket end date in UTC, inclusive (YYYY-MM-DD). For a partial bucket this is today's date.
      - `count` integer, required: Number of sales matching the player in this bucket window.
      - `total_amount` number, required: Sum of sale prices in USD across all matching sales.
      - `average_sale` number, required: Arithmetic mean sale price in USD (sum ÷ count). Returns 0 when `count` is 0.
      - `partial` boolean: True only for the in-progress current bucket. Always false for fully-closed historical buckets.

## Other responses

- `422`: Invalid request — most commonly `periods` exceeds the cap for the requested `interval` (day≤90, week≤52, month≤24).
- `502`: Upstream search backend error.
- `503`: Search is not configured on the server.

---

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