Search cards

Lucene query. Omit it to list everything. Full grammar in query syntax.

Comma-separated set codes, slugs or alternate ids. A shortcut for q=set.id:a OR set.id:b that does not need quoting.

Up to 4 keys, comma-separated, - for descending: id, name, number, rarity, hp, index_eur, last_price_at, updated_at, created_at, release_date, set, artist. A fifth key is QUERY_TOO_COMPLEX; an unsortable name is INVALID_PARAMETER. id is appended as tiebreaker whether you ask for it or not.

Accepted snake_case spelling of orderBy; the same sort keys and cursor rules apply.

Comma-separated card fields to return. id is always included. camelCase and snake_case both resolve, so nationalPokedexNumbers works and comes back as national_pokedex_numbers. An unknown name is INVALID_SELECT_FIELD, with the full list in details.valid_fields.

Comma-separated relations to expand: index, prices, translations, images, set, artist. Each one is an extra join, so ask only for what you render. include=index puts index_eur and last_price_at on the rows of a list or batch, at 1 credit per 50 cards requested. Without it they are not there: a select that names them gets rows without them and meta.withheld: ["index"], and an orderBy on them is 400 INVALID_PARAMETER. include=prices is how you get the per-source price breakdown, index included, and it makes the call a price call: 4 credits per 25 cards on a list or batch, 2 on a single card, and the rows are filtered by your plan exactly as on the price routes, with meta.withheld (the X-Plan-Withheld header on a single card) naming what was held back. A single card carries its index whatever you include. legalities is not an accepted value and is rejected with 400 INVALID_INCLUDE.

Locale for the card name: en, fr, de, ja, it, es, pt, zh — the eight with translation rows in the catalogue. A card with no translation in the requested locale falls back to English rather than to null.

Rows per page, 1 to 250. Card and sealed lists cost 1 credit per 50 rows requested, rounded up: 50 costs 1, 51 costs 2, 250 costs 5, so ask for multiples of 50. Above 250 you get LIMIT_EXCEEDED — follow links.next instead of raising it.

Opaque keyset cursor from links.next. Never construct one; it carries the sort order it was issued for and is rejected if orderBy changes mid-run.

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.