# List sets

> Every set with release date, totals, print region and series. An empty first-page name search retries exact market aliases, then order-independent words.

- **Endpoint**: `GET /v1/sets`
- **Cost**: 1 credit
- **Minimum plan**: free
- **Cache-Control**: `public, max-age=60, s-maxage=300, stale-while-revalidate=600`

Source: https://pokemontcgapi.com/docs/api/sets/list

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](https://pokemontcgapi.com/docs/quickstart) and the [pricing](https://pokemontcgapi.com/pricing).

A few hundred rows, so this response carries `meta.total_count` — the card endpoints do not, because counting a filtered card query exactly would cost more than the query itself.

The catalogue runs from **Expansion Pack**, 1996-10-20, to **30th Celebration**, 2026-09-16, across three print regions. Asian print lines are separate sets with their own codes and numbering, not translations of Western ones, which is what `region` is for.

`q` first keeps the existing name substring and code search. Only when its first page is empty does it try an exact normalized market name, then all distinct words in any order within a stored name or one market alias. `region` and `series` apply to every mode. Follow `links.next` unchanged: the cursor keeps the chosen mode. `lang` changes the displayed name; it does not search translations.

Successful retries add `meta.hints` with `SET_ALIAS_MATCHED` or `SET_WORDS_MATCHED` and the first matched name. A nonempty ordinary result never gains rows from aliases; each filtered market-name match outside the returned page gets a `SET_ALIAS_ELSEWHERE` hint with `set_code` and `set_name`. For example, `region=JP&q=team rocket` can keep an ordinary match while pointing to `rog` (Rocket Gang). `meta.hints` is absent when no suggestion applies. The cost remains one catalogue credit.

## Query parameters

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `q` | string | — | Accent-insensitive substring on the stored set name, or exact `code` or PTCGO code. Only an empty first page retries an exact market alias, then all distinct words in any order within one set name or alias. Existing matches always win. |
| `series` | string | — | Series slug, e.g. `base`. Sets whose series is unmapped match no value. |
| `lang` | string | — | Locale for the set name. If a translation is unavailable, the original name is returned. |
| `region` | string | — | Print region: `WEST` (176 sets), `JP` (380) or `CN` (96), counted 2026-09-18. `KR` is accepted and matches 0 rows. Anything else is `INVALID_PARAMETER` with the accepted values in `details.supported`. |
| `orderBy` | string | -release_date | One or more of `code`, `name`, `release_date`, `total`, `updated_at`. Tiebreaker is `code`. |
| `order_by` | string | — | Accepted snake_case spelling of `orderBy`; the same sort keys and cursor rules apply. |
| `limit` | integer | 50 | 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. |
| `cursor` | string | — | 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

| 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**

```bash
curl -s -G "https://api.pokemontcgapi.com/v1/sets" \
  --data-urlencode "region=JP" \
  --data-urlencode "limit=2" \
  -H "X-Api-Key: $PTCG_API_KEY"
```

**TypeScript**

`request.ts`

```ts
const url = new URL("https://api.pokemontcgapi.com/v1/sets");
url.searchParams.set("region", "JP");
url.searchParams.set("limit", "2");

const res = await fetch(url, {
  headers: { "X-Api-Key": process.env.PTCG_API_KEY ?? "" },
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
}

const { data, meta } = await res.json();
```

**Python**

`request.py`

```python
import os, httpx

res = httpx.get(
    "https://api.pokemontcgapi.com/v1/sets",
    params={"region": "JP", "limit": "2"},
    headers={"X-Api-Key": os.environ["PTCG_API_KEY"]},
)
res.raise_for_status()
payload = res.json()
```

## Example response

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

`response.json`

```json
{
  "data": [
    {
      "id": "m6",
      "code": "m6",
      "slug": "storm-emeralda",
      "legacy_id": null,
      "name": "Storm Emeralda",
      "series": null,
      "region": "JP",
      "release_date": "2026-07-31",
      "total": 116,
      "printed_total": null,
      "ptcgo_code": null,
      "symbol_url": null,
      "logo_url": "https://img.pokemontcgapi.com/media/sets/m6/logo-normal.webp?e=1791763200&s=Ck9pR3vZq2mTd8LwXa5nHy",
      "updated_at": "2026-08-26T17:47:39.900Z"
    },
    {
      "id": "m5",
      "code": "m5",
      "slug": "abyss-eye",
      "legacy_id": null,
      "name": "Abyss Eye",
      "series": null,
      "region": "JP",
      "release_date": "2026-05-22",
      "total": 118,
      "printed_total": null,
      "ptcgo_code": null,
      "symbol_url": null,
      "logo_url": "https://img.pokemontcgapi.com/media/sets/M5/logo-normal.webp?e=1791763200&s=Vt4bN7xQe1sJk0pM6cWyRz",
      "updated_at": "2026-08-26T17:47:39.900Z"
    }
  ],
  "meta": { "limit": 2, "count": 2, "total_count": 379, "has_more": true },
  "links": { "next": "https://api.pokemontcgapi.com/v1/sets?limit=2&region=JP&cursor=eyJrIjpbIjIwMjYtMDUtMjJUMDA6MDA6MDAuMDAwWiJdLCJ..." }
}
```

## 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. |
| 400 | `INVALID_CURSOR` | The cursor is malformed, or was issued for a different `orderBy` than the one on this request. |
| 400 | `LIMIT_EXCEEDED` | `limit` is above 250, or a batch request carries more than 100 ids. |
| 429 | `QUOTA_EXCEEDED` | Trial 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. |
| 403 | `PLAN_REQUIRED` | The 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. |
| 403 | `TRIAL_EXPIRED` | The 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](https://pokemontcgapi.com/docs/errors) page.

> **Unknown parameters return 400**
>
> An unknown query parameter returns `400 INVALID_PARAMETER` before credits are reserved. `details.param` names the rejected parameter, `details.valid_params` lists the accepted names, and `details.did_you_mean` suggests a likely correction when one exists. Use `cursor`, not `page` or `offset`.

## Regions, counted

| `region=` | Sets | What it covers |
| --- | --- | --- |
| `WEST` | 176 | The English-language print line and its European siblings |
| `JP` | 380 | Japanese sets, with their own codes and numbering |
| `CN` | 96 | Simplified Chinese print line |
| `KR` | 0 | Valid in the schema, no rows in the catalogue |

Those four numbers come from `meta.total_count` on `GET /v1/sets?region=…&limit=1`, which is the cheapest way to re-check them yourself.