Price history
A time series for one card: one point per day, week or month, per source and variant.
/v1/cards/{id}/prices/history5 creditsfree planCache-Control: public, max-age=300
Days with no observation are omitted, not interpolated: a straight line through a gap would be a claim we did not observe. Observations begin on 2026-07-28, the day the current ingest started, so a from before that returns the same series as from=2026-07-28.
The window is the plan’s: 7 days on the trial, 90 on Developer, the whole history on Growth and Professional. meta.plan_window_days reports the limit that applied (null when none did) and meta.truncated says whether from was moved. A series longer than the point cap is cut and flagged in meta.capped — pick a coarser bucket rather than paging.
Path parameters
| Name | Type | Default | Description |
|---|---|---|---|
id required | string | — | Card id or alternate id. |
Query parameters
| Name | Type | Default | Description |
|---|---|---|---|
source | string | — | One source code, e.g. CARDMARKET, CARDTRADER, TCGPLAYER or PTCG_INDEX. A chart that mixes sources means nothing, so filter to one. |
variant | string | — | One variant, e.g. MARKET, for the same reason. |
locale | string | — | Restrict to one printing language. |
printing | string | — | Restrict to one printing: HOLOFOIL, REVERSE_HOLO, … |
from | date | — | YYYY-MM-DD, inclusive. Defaults to the start of the plan’s window. |
to | date | — | YYYY-MM-DD, inclusive. Defaults to today. |
bucket | string | day | day, week or month. Coarser buckets keep a long window under the point cap. |
Headers
| Name | Type | Default | Description |
|---|---|---|---|
X-Api-Key required | string | — | Your API key. Authorization: Bearer <key> is accepted as an alias. |
If-None-Match | string | — | Send back the ETag you stored. The API returns a strong ETag on every catalogue response, and a 304 is a header exchange: no body, no database row read. |
Example request
curl -s -G "https://api.pokemontcgapi.com/v1/cards/base1-4/prices/history" \
--data-urlencode "source=TCGPLAYER" \
--data-urlencode "variant=MARKET" \
--data-urlencode "bucket=week" \
-H "X-Api-Key: $PTCG_API_KEY"Example response
200 OK · Cache-Control: public, max-age=300
{
"data": [
{
"date": "2026-07-27",
"source": "TCGPLAYER",
"variant": "MARKET",
"locale": "en",
"printing": "HOLOFOIL",
"amount": 800.43,
"currency": "USD",
"sample_n": 0
},
{
"date": "2026-07-27",
"source": "TCGPLAYER",
"variant": "MARKET",
"locale": "en",
"printing": null,
"amount": 800.43,
"currency": "USD",
"sample_n": 0
},
{
"date": "2026-08-03",
"source": "TCGPLAYER",
"variant": "MARKET",
"locale": "en",
"printing": null,
"amount": 818.65,
"currency": "USD",
"sample_n": 0
},
{
"date": "2026-08-10",
"source": "TCGPLAYER",
"variant": "MARKET",
"locale": "en",
"printing": null,
"amount": 825.38,
"currency": "USD",
"sample_n": 0
},
{
"date": "2026-08-17",
"source": "TCGPLAYER",
"variant": "MARKET",
"locale": "en",
"printing": null,
"amount": 855.52,
"currency": "USD",
"sample_n": 0
},
{
"date": "2026-08-24",
"source": "TCGPLAYER",
"variant": "MARKET",
"locale": "en",
"printing": null,
"amount": 855.52,
"currency": "USD",
"sample_n": 0
},
{
"date": "2026-08-31",
"source": "TCGPLAYER",
"variant": "MARKET",
"locale": "en",
"printing": null,
"amount": 868.56,
"currency": "USD",
"sample_n": 0
}
],
"meta": {
"card_id": "base1-4",
"from": "2026-06-04",
"to": "2026-09-02",
"bucket": "week",
"count": 7,
"truncated": false,
"capped": false,
"plan_window_days": null
}
}Errors
Every error body carries error.code, error.message and error.request_id. Switch on the code, never on the message.
| Status | Code | When |
|---|---|---|
| 401 | MISSING_API_KEY | No X-Api-Key header and no bearer token on a route that requires one. |
| 401 | INVALID_API_KEY | The key does not match any account. |
| 400 | INVALID_PARAMETER | A query parameter has the wrong type or an unsupported value — a non-integer limit, an unknown lang, an unknown region, a sort key that is not sortable. |
| 403 | UPGRADE_REQUIRED | A parameter asks for more than the plan allows: a window longer than the plan’s history, for example. details.plan_window_days says how much the plan gives. |
The full taxonomy, with what to do about each code, is on the errors page.