Get a card's price statistics

GET/v1/cards/{id}/price-stats

Get aggregate price statistics for one card over a trailing window (7, 30, or 90 days), broken out per variant in data.variants so printings (e.g. Normal and Holofoil) are never blended together: each entry has min, max, average (integer cents), the first and last price in the window with their dates, absolute and percent change first to last, and the number of data points. The variant param restricts the response to a single entry. window_start and window_end apply to the whole response. When no price data falls in the window, returns 200 with an empty data.variants array, not an error. Requires a paid plan (starter, pro, or business); a free-plan key gets a 403 plan_limit error. The requested window is also bounded by your plan's price-history range.

Auth: send Authorization: Bearer bdx_live_... (or X-API-Key) from a server-side integration. Sandbox keys get 403 sandbox_key.

Response shape

Field	Type	Required	Description
`currency`	`string`	—	Always USD today. "USD" const: USD
`data`	`object`	—	—
`data.variants`	`array<object>`	—	—
`data.variants[].average_price_cents`	`integer \| null`	—	—
`data.variants[].change_cents`	`integer \| null`	—	—
`data.variants[].change_percent`	`number \| null`	—	—
`data.variants[].data_points`	`integer`	—	—
`data.variants[].first`	`object \| null`	—	—
`data.variants[].first.date`	`string`	—	format: date
`data.variants[].first.price_cents`	`integer`	—	—
`data.variants[].last`	`object \| null`	—	—
`data.variants[].last.date`	`string`	—	format: date
`data.variants[].last.price_cents`	`integer`	—	—
`data.variants[].max_price_cents`	`integer \| null`	—	—
`data.variants[].min_price_cents`	`integer \| null`	—	—
`data.variants[].variant`	`string`	—	—
`id`	`string`	—	—
`variant`	`string \| null`	—	—
`window`	`string`	—	["7d","30d","90d"] enum: ["7d","30d","90d"]
`window_end`	`string`	—	format: date-time
`window_start`	`string`	—	format: date-time

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Card id or slug.
`window`	query	`string`	—	Trailing window: 7d, 30d, or 90d. Your plan may cap this lower. default: 30d · enum: ["7d","30d","90d"]
`variant`	query	`string`	—	Restrict to one variant, e.g. Holofoil. Defaults to every variant BinderDex tracks for the card. minLength: 1 · maxLength: 64

Example

Example responsejson

{
  "currency": "USD",
  "data": {
    "variants": [
      {
        "average_price_cents": 5050,
        "change_cents": 100,
        "change_percent": 2,
        "data_points": 3,
        "first": {
          "date": "2026-08-20",
          "price_cents": 5000
        },
        "last": {
          "date": "2026-09-18",
          "price_cents": 5100
        },
        "max_price_cents": 5100,
        "min_price_cents": 5000,
        "variant": "Holofoil"
      },
      {
        "average_price_cents": 1150,
        "change_cents": 300,
        "change_percent": 30,
        "data_points": 3,
        "first": {
          "date": "2026-08-20",
          "price_cents": 1000
        },
        "last": {
          "date": "2026-09-18",
          "price_cents": 1300
        },
        "max_price_cents": 1300,
        "min_price_cents": 1000,
        "variant": "Normal"
      }
    ]
  },
  "id": "card_9f2c1b7a",
  "variant": null,
  "window": "30d",
  "window_end": "2026-09-18T04:00:00Z",
  "window_start": "2026-08-19T04:00:00Z"
}

Possible errors

Every error below uses the Error envelope with a request ID. Retry only when the response’s documented semantics identify a temporary condition; see errors and versioning for the detailed guidance.