Search cards

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.

The main read path. q accepts a Lucene-style query grammar — field terms, phrases, booleans, wildcards and ranges — documented in full in query syntax.

Collector number uses an exact match first. Only if the first page is empty does a simple positive number term retry without leading zeros; number:N/M also checks the set’s printed total when known. Vintage Japanese cards may use set position as number: search their species with nationalPokedexNumbers. meta.hints appears only when a normalized retry succeeds or a still-empty result has a Pokédex suggestion.

Results are ordered by id unless you say otherwise, and every sort ends with id as a tiebreaker. That is not a detail: without it, two cards sharing a sort key have undefined relative order between queries, and paging silently duplicates and drops rows.

A bare row is catalogue: name, number, rarity, set, game text. The composite index — index_eur and last_price_at — comes onto the rows with include=index, at the same 1 credit per 50 cards requested as the bare list, and a price-sorted list is then one request with no second round trip. The list itself is priced per 50 rows requested since 2026-09-30, and every card it returns counts towards the distinct-card allowance of the plan (1,000 on the trial, 30,000 a month on Developer, none from Growth up): a full mirror is a Growth job. Sorting on those two fields without the include is a 400 that says so; selecting them without it leaves them out and says so in meta.withheld. The example below sorts the whole catalogue by our composite index.

Query parameters

Headers

Example request

curl -s -G "https://api.pokemontcgapi.com/v1/cards" \
  --data-urlencode "q=name:charizard" \
  --data-urlencode "include=index" \
  --data-urlencode "orderBy=-index_eur" \
  --data-urlencode "limit=2" \
  --data-urlencode "select=id,name,number,rarity,set_code,set_name,release_date,artist_name,index_eur,last_price_at" \
  -H "X-Api-Key: $PTCG_API_KEY"

Example response

200 OK · Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=600

{
  "data": [
    {
      "id": "nde-107",
      "name": "Shining Charizard",
      "number": "107",
      "rarity": "Rare Shining",
      "index_eur": 5894.78,
      "last_price_at": "2026-08-26T19:03:20.955Z",
      "set_code": "nde",
      "set_name": "Neo Destiny",
      "release_date": "2002-02-28",
      "artist_name": "Hironobu Yoshida"
    },
    {
      "id": "e5-089",
      "name": "Charizard",
      "number": "089",
      "rarity": "Secret Rare",
      "index_eur": 5371.99,
      "last_price_at": "2026-08-26T19:03:20.955Z",
      "set_code": "e5",
      "set_name": "Mysterious Mountains",
      "release_date": "2002-10-04",
      "artist_name": null
    }
  ],
  "meta": { "limit": 2, "count": 2, "has_more": true },
  "links": {
    "next": "https://api.pokemontcgapi.com/v1/cards?q=name%3Acharizard&include=index&orderBy=-index_eur&limit=2&cursor=eyJrIjpbNTM3MS45OV0sImlkIjoiZTUtMDg5Iiwicy..."
  }
}

Errors

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

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

Paging a full result set

For a complete card import, start at GET /v1/cards?limit=250&orderBy=id. Add q=set.region:JP or q=set.region:CN for one print region. Use a set filter or /v1/sets/{code}/cards when you only need a particular set. See the quickstart for dated request counts.

Follow links.next until it is absent. Do not rebuild the URL yourself and do not change orderBy between pages — the cursor carries the sort order it was issued for, and a mismatch is rejected with INVALID_CURSOR rather than quietly skipping rows.

let next: string | null =
  "https://api.pokemontcgapi.com/v1/cards?limit=250&orderBy=id";

while (next) {
  const res = await fetch(next, { headers: { "X-Api-Key": key } });
  const page = await res.json();
  for (const card of page.data) upsert(card);
  next = page.links?.next ?? null;
}

What the catalogue holds

This endpoint searches identity, printing and price: name, number, rarity, HP, set, series, region, artist and the composite index. Rules text — attacks, abilities, subtypes, flavour text — is declared in the schema and carries no rows today, so a query that filters on it matches nothing. The card object states the coverage of every field with the date it was measured.