Skip to content
pokemontcgapi.com
sign in
Documentation

Price stats

Low, high, median, first, last and the percentage change of the composite index over a window.

GET/v1/cards/{id}/prices/stats2 creditsfree plan

Cache-Control: private, max-age=300

Objects returned

No key yet? One call gets you one: POST /v1/accounts/free with an Idempotency-Key header and your email address returns a working key in the response. Keep the original Idempotency-Key and body for response replay for up to 24 hours, under the conditions in the quickstart. The trial is 800 credits over 30 days once the address is confirmed, no card; paid plans start at 29 € a month. See the quickstart and the pricing.

Always computed on PTCG_INDEX, in EUR — the one series that exists for every priced card and is comparable across them. sample_n is the number of index points in the window; zero means the card had no index in that period, and every other field is null.

Two credits, not five: a stats call reads the index rows of one card, which is a fraction of what a history call touches.

Path parameters

Path parameters
NameTypeDefaultDescription
id requiredstring—Card id or alternate id.

Query parameters

Query parameters
NameTypeDefaultDescription
windowstring30d7d, 30d, 90d or 365d. A window longer than the plan’s history is UPGRADE_REQUIRED, with details.plan_window_days and details.next_step.
localestring—The printing language of the index series to summarise. The index is one series per language, so a summary across languages would compare a French point with a Spanish one. Unset, it is the language of the card’s print region — en for Western printings, ja, zh or ko for the others — and meta.locale says which one was used.

Headers

Headers
NameTypeDefaultDescription
X-Api-Key requiredstring—Your API key. Authorization: Bearer <key> is accepted as an alias.
If-None-Matchstring—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/stats" \
  --data-urlencode "window=30d" \
  -H "X-Api-Key: $PTCG_API_KEY"

Example response

200 OK · Cache-Control: private, max-age=300

response.json
{
  "data": {
    "window": "30d",
    "from": "2026-08-03",
    "to": "2026-09-02",
    "low": 431.41,
    "high": 431.41,
    "median": 431.41,
    "first": 431.41,
    "last": 431.41,
    "change_pct": 0,
    "sample_n": 1,
    "currency": "EUR"
  },
  "meta": {
    "card_id": "base1-4",
    "source": "PTCG_INDEX"
  }
}

Errors

Every error body carries error.code, error.message and error.request_id. Switch on the code, never on the message.

Errors returned by this endpoint
StatusCodeWhen
401MISSING_API_KEYNo X-Api-Key header and no bearer token on a route that requires one.
401INVALID_API_KEYThe key does not match any account.
400INVALID_PARAMETERA 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.
403UPGRADE_REQUIREDA 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; details.next_step carries the owner action and handoff.
429QUOTA_EXCEEDEDTrial credits, monthly credits or the daily cap are exhausted, and details says which: daily_cap with retry_after_s is the trial daily cap, which resets at midnight UTC; renews: true with resets_at is the monthly quota of a paid plan; renews: false is the trial allowance, which never comes back. details.next_step carries the plan, prices and owner action, or email verification when it unlocks the full trial.
403PLAN_REQUIREDThe feature is outside the plan (movers require Growth; photo recognition has 5 calls after Free email confirmation, then requires Growth), or the account subscription is canceled or suspended. Centering requires Growth or higher; Developer is excluded. After email confirmation the trial includes 5 measure and 5 confirm calls independently; grade and standards use trial credits without separate call counters. Before email confirmation, the message starts with “Confirm your email…”. Follow details.next_step when present.
403TRIAL_EXPIREDThe trial has ended: the account is on the trial and its 30 days from signup are over, and this route costs credits. details.trial_expired_at is the date, details.trial_days the length, and details.next_step the owner handoff. Zero-cost routes — /v1/me, /v1/me/usage, the key routes and /v1/billing/checkout — still answer.

The full taxonomy, with what to do about each code, is on the errors page.

view this page as markdown