Skip to content
pokemontcgapi.com
sign in
Documentation

Cards in a set

Every card in a set, in collection order, with correct paging past 250 rows.

GET/v1/sets/{code}/cards1 credit per 50 cards requested (the limit), rounded up; include=index costs the same; with include=prices, 4 credits per 25free plan

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

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.

An unknown code returns 404 SET_NOT_FOUND, never an empty page. An empty page reads as "this set was emptied" and is the fastest way to get a wrong bug report written about you.

For q=number:22, an exact set match wins; if it is empty, the API can find 022. q=number:22/185 also requires this set’s printed_total to be 185 when known. A still-empty vintage Japanese lookup may carry a TRY_POKEDEX_NUMBER hint with a nationalPokedexNumbers query to copy. See query syntax.

This is the endpoint where a missing sort tiebreaker does the most damage: a set over 250 cards spans several pages, and rows sharing a collector number would land in undefined order at every boundary. Here the sort is (number_sort, number, id) and id is never optional, so pagination never repeats or drops a row, at any page depth.

Path parameters

Path parameters
NameTypeDefaultDescription
code requiredstring—Set code, slug or alternate id.

Query parameters

Query parameters
NameTypeDefaultDescription
qstring—Further Lucene filter, applied inside the set.
orderBystringnumberDefaults to collection order. Same keys as search cards. number sorts on the extracted numeric part first, so 1S lands next to 1 and not next to 100.
order_bystring—Accepted snake_case spelling of orderBy; the same sort keys and cursor rules apply.
selectstring—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.
includestring—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.
langstring—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.
limitinteger50Rows 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.
cursorstring—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.

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/sets/bs/cards" \
  --data-urlencode "limit=2" \
  --data-urlencode "include=index" \
  --data-urlencode "select=id,name,number,rarity,index_eur" \
  -H "X-Api-Key: $PTCG_API_KEY"

Example response

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

response.json
{
  "data": [
    { "id": "bs-1", "name": "Alakazam", "number": "1", "rarity": "Rare Holo", "index_eur": 48.83 },
    { "id": "bs-1s", "name": "Alakazam (1st Edition Shadowless)", "number": "1S", "rarity": "Rare Holo", "index_eur": 49.30 }
  ],
  "meta": { "limit": 2, "count": 2, "has_more": true },
  "links": { "next": "https://api.pokemontcgapi.com/v1/sets/bs/cards?include=index&select=id%2Cname%2Cnumber%2Crarity%2Cindex_eur&limit=2&cursor=eyJrIjpbMSwiMVMiXSwiaWQ..." }
}

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.
404SET_NOT_FOUNDNo set with that code, slug or alternate id.
400INVALID_QUERYThe q parameter does not parse, or names a field that does not exist.
400INVALID_CURSORThe cursor is malformed, or was issued for a different orderBy than the one on this request.
400LIMIT_EXCEEDEDlimit is above 250, or a batch request carries more than 100 ids.
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.
403CARD_ALLOWANCE_EXCEEDEDThe account has retrieved as many distinct cards as its plan covers in the period — 1,000 for the whole trial, 30,000 a month on Developer; Growth and above have no limit — and this request would add new ones. details.cards_used, details.card_allowance and details.new_cards give the numbers, details.resets_at the next period on paid plans, and details.next_step the owner handoff. Only the card routes count; the page that crossed the limit was served in full, and cards already retrieved keep answering.

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

Print variants are separate rows with their own ids and their own prices — bs-1 and bs-1s above are the same Alakazam in two printings, and each carries its own index_eur once you include=index. That is why a set can hold more rows than its printed_total.

view this page as markdown