Pokémon TCG API

https://pokemontcgapi.com/docs
Admin
Pokémon TCG API is a REST API providing comprehensive data and current market prices for Pokémon...
Tokens:112,279
Snippets:598
Trust Score:2.3
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Sealed product object example (JSON)

Source: https://pokemontcgapi.com/docs/objects/sealed

Example response for a sealed product object, as returned by GET /v1/sealed and GET /v1/sealed/{id}. Shows all 15 fields, including id equal to sku, nullable fields like slug and pack_count, and the languages array.

```json
{
  "id": "SV2a-booster-box",
  "sku": "SV2a-booster-box",
  "slug": null,
  "name": "Pokemon Card 151 Booster Box",
  "kind": "BOOSTER_BOX",
  "set_code": "sv2a",
  "set_name": "Pokemon Card 151",
  "image_url": "https://media.rarebit.app/boxes/SV2a-booster-box-normal.webp",
  "release_date": "2023-06-16",
  "pack_count": null,
  "languages": [
    "ja"
  ],
  "index_eur": null,
  "last_price_at": "2026-06-23T01:24:42.794Z",
  "created_at": "2026-06-12T10:29:43.290Z",
  "updated_at": "2026-09-02T15:56:54.473Z"
}
```

--------------------------------

### Example request: curl

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

Sends a GET request to /v1/sets/bs/cards with limit, include, and select parameters, using the X-Api-Key header.

```bash
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 from GET /v1/prices/sources

Source: https://pokemontcgapi.com/docs/api/prices/sources

Shows the JSON response containing an array of price sources with fields: source, label, min_delay_hours, and is_own. The response includes a count of 7 sources.

```json
{
  "data": [
    {
      "source": "CARDMARKET",
      "label": "Cardmarket",
      "min_delay_hours": 24,
      "is_own": false
    },
    {
      "source": "CARDTRADER",
      "label": "CardTrader",
      "min_delay_hours": 24,
      "is_own": false
    },
    {
      "source": "COMMUNITY",
      "label": "Community-observed",
      "min_delay_hours": 0,
      "is_own": false
    },
    {
      "source": "EBAY",
      "label": "eBay",
      "min_delay_hours": 24,
      "is_own": false
    },
    {
      "source": "PRICECHARTING",
      "label": "PriceCharting",
      "min_delay_hours": 24,
      "is_own": false
    },
    {
      "source": "PTCG_INDEX",
      "label": "pokemontcgapi composite index",
      "min_delay_hours": 0,
      "is_own": true
    },
    {
      "source": "TCGPLAYER",
      "label": "TCGplayer",
      "min_delay_hours": 24,
      "is_own": false
    }
  ],
  "count": 7
}
```

--------------------------------

### GET /v1/prices/movers - Example JSON response

Source: https://pokemontcgapi.com/docs/api/prices/movers

The 200 OK response body returned for the example request, showing three gainers with their index values and metadata. The response is cached for 300 seconds.

```json
{
  "data": [
    {
      "card_id": "adv1-002",
      "name": "Weezing",
      "set_code": "adv1",
      "from": 7.23,
      "to": 7.23,
      "change_pct": 0,
      "currency": "EUR"
    },
    {
      "card_id": "adv1-003",
      "name": "Sceptile",
      "set_code": "adv1",
      "from": 21.56,
      "to": 21.56,
      "change_pct": 0,
      "currency": "EUR"
    },
    {
      "card_id": "adv1-006",
      "name": "Beautifly",
      "set_code": "adv1",
      "from": 6.73,
      "to": 6.73,
      "change_pct": 0,
      "currency": "EUR"
    }
  ],
  "meta": {
    "window": "90d",
    "from": "2026-06-04",
    "to": "2026-09-02",
    "direction": "gainers",
    "min_value": 5,
    "count": 3,
    "source": "PTCG_INDEX"
  }
}
```

--------------------------------

### orderBy parameter example

Source: https://pokemontcgapi.com/docs/pagination

Shows how to sort results by multiple keys, with a leading minus for descending order. The example sorts by release_date descending and name ascending.

```text
orderBy=-release_date,name
```

--------------------------------

### GET /v1/sets

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

Documentation for the GET /v1/sets endpoint, including query parameters, headers, and example request.

```APIDOC
## [GET] /v1/sets

### Description
Lists Pokémon TCG card sets with filtering, pagination, and sorting options.

### Method
GET

### Endpoint
https://api.pokemontcgapi.com/v1/sets

### Parameters
#### Query Parameters
- **q** (string) - Optional - Accent-insensitive substring match on the set name, or an exact `code` or `slug`.
- **series** (string) - Optional - Series slug, e.g. `base`. Sets whose series is unmapped match no value.
- **region** (string) - Optional - 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) - Optional - Default: `-release_date`. One or more of `code`, `name`, `release_date`, `total`, `updated_at`. Tiebreaker is `code`.
- **limit** (integer) - Optional - Default: 50. Rows per page, 1 to 250. Above 250 you get `LIMIT_EXCEEDED` — follow `links.next` instead of raising it.
- **cursor** (string) - Optional - 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
- **X-Api-Key** (string) - Required - Your API key. `Authorization: Bearer <key>` is accepted as an alias.
- **If-None-Match** (string) - Optional - 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.

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

### Response
#### Success Response (200)
Returns a paginated list of sets. The response includes an `ETag` header for caching.

#### Error Handling
- `INVALID_PARAMETER` - Returned for invalid `region` values, with accepted values in `details.supported`.
- `LIMIT_EXCEEDED` - Returned when `limit` exceeds 250. Follow `links.next` instead.
- `304 Not Modified` - Returned when `If-None-Match` matches the current `ETag`. No body is returned.
```

--------------------------------

### Example response for free key creation

Source: https://pokemontcgapi.com/docs/api/accounts/free

Example response from POST /v1/accounts/free with status 201 OK and Cache-Control: no-store. Only the key secret is shown; other account, key, and quota fields are omitted.

```json
{"data":{"key":{"secret":"ptcg_live_example"}}}

```

--------------------------------

### Example response for GET /v1/sets/{code}

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

Shows the JSON response for a successful request (200 OK). The response includes the set's id, code, slug, legacy_id, name, series, region, release_date, totals, ptcgo_code, symbol_url, logo_url, and updated_at.

```json
{
  "id": "bs",
  "code": "bs",
  "slug": "base",
  "legacy_id": "base1",
  "name": "Base",
  "series": "Base",
  "region": "WEST",
  "release_date": "1999-01-09",
  "total": 134,
  "printed_total": 102,
  "ptcgo_code": "BS",
  "symbol_url": null,
  "logo_url": "https://media.rarebit.app/sets/BASE/logo-normal.webp",
  "updated_at": "2026-08-26T17:47:39.900Z"
}
```

--------------------------------

### Example response: response.json

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

Shows the JSON response for the example request, including data array with card objects, meta, and links.

```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..." }
}
```

--------------------------------

### List artists example response

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

Example response for a successful request, returning a single artist with a card count and metadata.

```json
{
  "data": [
    { "slug": "mitsuhiro-arita", "name": "Mitsuhiro Arita", "card_count": 760 }
  ],
  "meta": { "limit": 3, "count": 1, "total_count": 1, "has_more": false }
}

```

--------------------------------

### Price JSON example

Source: https://pokemontcgapi.com/docs/objects/price

Example of a Price object from the PTCG_INDEX source, showing a derived index price in EUR.

```json
{
  "source": "PTCG_INDEX",
  "variant": "INDEX",
  "basis": "DERIVED",
  "amount": 561.84,
  "currency": "EUR",
  "locale": "en",
  "condition": null,
  "printing": "HOLOFOIL",
  "grading": null,
  "as_of": "2026-08-26",
  "sample_n": 2,
  "provenance": "pokemontcgapi composite index"
}
```

--------------------------------

### Example response for list series

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

Example response for the series list request. Shows the data array with series objects, meta with pagination info, and a links.next cursor for the next page.

```json
{
  "data": [
    {
      "id": "sword-shield",
      "slug": "sword-shield",
      "name": "Sword & Shield",
      "set_count": 22
    },
    {
      "id": "ex",
      "slug": "ex",
      "name": "EX",
      "set_count": 20
    },
    {
      "id": "scarlet-violet",
      "slug": "scarlet-violet",
      "name": "Scarlet & Violet",
      "set_count": 18
    }
  ],
  "meta": {
    "limit": 3,
    "count": 3,
    "total_count": 17,
    "has_more": true
  },
  "links": {
    "next": "https://api.pokemontcgapi.com/v1/series?cursor=eyJrIjpbMThdLCJpZCI6InNjYXJsZXQtdmlvbGV0IiwicyI6InNldF9jb3VudDpkZXNjLHNsdWc6YXNjIn0&limit=3"
  }
}
```

--------------------------------

### Example response for get artist

Source: https://pokemontcgapi.com/docs/api/artists/get

Example 200 OK response body for the get artist endpoint. Contains the artist's slug, name, and card_count.

```json
{ "slug": "mitsuhiro-arita", "name": "Mitsuhiro Arita", "card_count": 760 }
```

--------------------------------

### Example response for /v1/sets

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

Example JSON response from the /v1/sets endpoint, showing two sets with metadata and pagination links. The response includes fields like id, code, slug, name, region, release_date, total, and logo_url.

```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://media.rarebit.app/sets/m6/logo-normal.webp",
      "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://media.rarebit.app/sets/M5/logo-normal.webp",
      "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..." }
}
```

--------------------------------

### Example response for GET /v1/status

Source: https://pokemontcgapi.com/docs/api/status/get

Example 200 OK response from GET /v1/status. Contains catalog counts, ingest job timestamps and ages, and upstream contract status. The response is cached with Cache-Control: public, max-age=60.

```json
{
  "status": "ok",
  "catalog": {
    "sets": 651,
    "cards": 57450,
    "sealed": 2091,
    "artists": 402
  },
  "sources": [
    {
      "source": "refresh-catalog",
      "last_success_at": "2026-09-02T22:21:28.703Z",
      "age_hours": 0.9,
      "state": "fresh"
    },
    {
      "source": "refresh-index",
      "last_success_at": "2026-09-02T23:09:52.114Z",
      "age_hours": 0.1,
      "state": "fresh"
    },
    {
      "source": "refresh-prices",
      "last_success_at": "2026-09-02T23:07:22.204Z",
      "age_hours": 0.1,
      "state": "fresh"
    }
  ],
  "upstream": {
    "contract_ok": true,
    "error": null
  },
  "version": "dev"
}
```

--------------------------------

### GET /v1/cards/{id}/prices/stats

Source: https://pokemontcgapi.com/docs/api/prices/stats

Documentation for the GET /v1/cards/{id}/prices/stats endpoint, including parameters, headers, example request and response, and error codes.

```APIDOC
## GET /v1/cards/{id}/prices/stats

### Description
Returns low, high, median, first, last and the percentage change of the composite index over a window for a given card. The index is always computed on PTCG_INDEX in EUR.

### Method
GET

### Endpoint
/v1/cards/{id}/prices/stats

### Parameters
#### Path Parameters
- **id** (string) - Required - Card id or alternate id.

#### Query Parameters
- **window** (string) - Optional - `7d`, `30d`, `90d` or `365d`. A window longer than the plan’s history is `UPGRADE_REQUIRED`, with `details.plan_window_days` and `details.next_step`. Default: `30d`.
- **locale** (string) - Optional - The printing language of the index series to summarise. 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
- **X-Api-Key** (string) - Required - Your API key. `Authorization: Bearer <key>` is accepted as an alias.
- **If-None-Match** (string) - Optional - 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.

### Request Example
```
curl -s -G "https://api.pokemontcgapi.com/v1/cards/base1-4/prices/stats" \
  --data-urlencode "window=30d" \
  -H "X-Api-Key: $PTCG_API_KEY"
```

### Response
#### Success Response (200)
- **data.window** (string) - The requested window.
- **data.from** (string) - Start date of the window.
- **data.to** (string) - End date of the window.
- **data.low** (number) - Lowest index value in the window.
- **data.high** (number) - Highest index value in the window.
- **data.median** (number) - Median index value in the window.
- **data.first** (number) - First index value in the window.
- **data.last** (number) - Last index value in the window.
- **data.change_pct** (number) - Percentage change over the window.
- **data.sample_n** (integer) - Number of index points in the window; zero means the card had no index in that period, and every other field is null.
- **data.currency** (string) - Currency of the index (EUR).
- **meta.card_id** (string) - The card id.
- **meta.source** (string) - The index source (PTCG_INDEX).

#### Response Example
```
{
  "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.

| 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. |
| 403 | `UPGRADE_REQUIRED` | A 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. |
| 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 (photo recognition and movers require Growth), or the account subscription is canceled or suspended. `details.next_step` carries the owner action and handoff. |
| 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. |
```

--------------------------------

### Example request: curl

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

Fetch the first page of changes with a limit of 2. Requires a valid API key in the X-Api-Key header. The response is documented on the same page and is shown in its own snippet.

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

--------------------------------

### GET /v1/status with curl

Source: https://pokemontcgapi.com/docs/api/status/get

Sends a GET request to the /v1/status endpoint. The endpoint is free and does not require a key, but the example includes an X-Api-Key header. The response is cached with Cache-Control: public, max-age=60.

```bash
curl -s "https://api.pokemontcgapi.com/v1/status" \
  -H "X-Api-Key: $PTCG_API_KEY"
```

--------------------------------

### Example response: 200 OK for /v1/changes

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

The JSON body returned by the example request. It shows the data array with two INSERT operations, pagination meta (next_since, watermark, oldest_available, behind), and the links.next URL to follow for more pages.

```json
{
  "data": [
    {
      "id": 1,
      "kind": "SET",
      "entity_id": "sv2a",
      "op": "INSERT",
      "version": 1,
      "changed_at": "2026-09-02T12:39:35.894Z"
    },
    {
      "id": 2,
      "kind": "SET",
      "entity_id": "svln",
      "op": "INSERT",
      "version": 1,
      "changed_at": "2026-09-02T12:39:35.894Z"
    }
  ],
  "meta": {
    "count": 2,
    "has_more": true,
    "next_since": 2,
    "watermark": 116242,
    "oldest_available": 1,
    "behind": 116240
  },
  "links": {
    "next": "https://api.pokemontcgapi.com/v1/changes?limit=2&since=2"
  }
}
```

--------------------------------

### GET /v1/prices/movers - Example curl request

Source: https://pokemontcgapi.com/docs/api/prices/movers

Lists the top price movers over a 90-day window with a minimum value of 5 EUR and a limit of 3, using an X-Api-Key header. Replace $PTCG_API_KEY with your actual key.

```bash
curl -s -G "https://api.pokemontcgapi.com/v1/prices/movers" \
  --data-urlencode "window=90d" \
  --data-urlencode "min_value=5" \
  --data-urlencode "limit=3" \
  -H "X-Api-Key: $PTCG_API_KEY"
```

--------------------------------

### Example response from /v1/sealed

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

Example 200 OK response from the /v1/sealed endpoint. Includes data array, meta with pagination info, and links with a next cursor. The response is cached with Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=600.

```json
{
  "data": [
    {
      "id": "evolving-skies-6-booster-box-case",
      "sku": "evolving-skies-6-booster-box-case",
      "slug": "evolving-skies-6-booster-box-case",
      "name": "Evolving Skies 6 Booster Box Case",
      "kind": "BOOSTER_BOX",
      "set_code": "evs",
      "set_name": "Evolving Skies",
      "image_url": "https://media.rarebit.app/boxes/evolving-skies-6-booster-box-case-normal.webp",
      "release_date": null,
      "pack_count": 216,
      "languages": [],
      "index_eur": 15495,
      "last_price_at": "2026-09-02T00:38:55.286Z",
      "created_at": "2026-05-23T12:43:56.128Z",
      "updated_at": "2026-09-02T15:56:54.473Z"
    },
    {
      "id": "evolving-skies-booster-box",
      "sku": "evolving-skies-booster-box",
      "slug": "evolving-skies-booster-box",
      "name": "Evolving Skies Booster Box",
      "kind": "BOOSTER_BOX",
      "set_code": "evs",
      "set_name": "Evolving Skies",
      "image_url": "https://media.rarebit.app/boxes/evolving-skies-booster-box-normal.webp",
      "release_date": null,
      "pack_count": 36,
      "languages": [],
      "index_eur": 1750,
      "last_price_at": "2026-09-02T00:36:37.317Z",
      "created_at": "2026-05-23T12:43:56.069Z",
      "updated_at": "2026-09-02T15:56:54.473Z"
    }
  ],
  "meta": {
    "limit": 2,
    "count": 2,
    "total_count": 3,
    "has_more": true
  },
  "links": {
    "next": "https://api.pokemontcgapi.com/v1/sealed?cursor=eyJrIjpbbnVsbF0sImlkIjoiZXZvbHZpbmctc2tpZXMtYm9vc3Rlci1ib3giLCJzIjoicmVsZWFzZV9kYXRlOmRlc2Msc2t1OmFzYyJ9&kind=BOOSTER_BOX&limit=2&q=evolving+skies"
  }
}
```

--------------------------------

### Reference list response JSON

Source: https://pokemontcgapi.com/docs/api/reference/lists

Example response from GET /v1/reference with status 200 OK and Cache-Control: public, max-age=86400. Contains all closed vocabularies: locales, currencies, print regions, conditions, printings, grading companies, price variants, price bases, change kinds, image faces, and image sizes.

```json
{
  "data": {
    "locales": [
      "en",
      "ja",
      "zh",
      "fr",
      "de",
      "es",
      "it",
      "pt",
      "ko"
    ],
    "currencies": [
      "EUR",
      "USD",
      "GBP",
      "JPY"
    ],
    "print_regions": [
      "WEST",
      "JP",
      "CN",
      "KR"
    ],
    "conditions": [
      "MINT",
      "NEAR_MINT",
      "EXCELLENT",
      "GOOD",
      "LIGHT_PLAYED",
      "PLAYED",
      "POOR"
    ],
    "printings": [
      "NORMAL",
      "HOLOFOIL",
      "REVERSE_HOLO",
      "FIRST_EDITION",
      "FIRST_EDITION_HOLOFOIL"
    ],
    "grading_companies": [
      "PSA",
      "BGS",
      "CGC",
      "SGC",
      "ACE",
      "TAG"
    ],
    "price_variants": [
      "LOW",
      "MARKET",
      "TREND",
      "AVG_1D",
      "AVG_7D",
      "AVG_30D",
      "MEDIAN_GRADED",
      "INDEX"
    ],
    "price_bases": [
      "SOLD",
      "ASKING",
      "GUIDE",
      "DERIVED"
    ],
    "change_kinds": [
      "CARD",
      "SET",
      "SEALED",
      "PRICE",
      "IMAGE"
    ],
    "image_faces": [
      "FRONT",
      "BACK",
      "ART",
      "LOGO",
      "SYMBOL"
    ],
    "image_sizes": [
      "SMALL",
      "NORMAL",
      "LARGE"
    ]
  }
}
```

--------------------------------

### Set Object

Source: https://pokemontcgapi.com/docs/objects/set

The Set object represents an expansion in the Pokémon TCG API. It includes fields such as id, code, slug, legacy_id, name, series, region, release_date, total, printed_total, ptcgo_code, symbol_url, logo_url, and updated_at. This object is returned by the endpoints GET /v1/sets, GET /v1/sets/{code}, GET /v1/sets/{code}/cards, and GET /v1/series.

```APIDOC
## Set Object

### Description
The Set object represents an expansion in the Pokémon TCG API. It includes fields such as id, code, slug, legacy_id, name, series, region, release_date, total, printed_total, ptcgo_code, symbol_url, logo_url, and updated_at. This object is returned by the endpoints GET /v1/sets, GET /v1/sets/{code}, GET /v1/sets/{code}/cards, and GET /v1/series.

### Fields

| Field | Type | Null | Description |
| --- | --- | --- | --- |
| `id` | string | no | Same value as `code`. Present so code that stores one id field keeps compiling. |
| `code` | string | no | Canonical code, e.g. `bs`. The natural key across every importer. |
| `slug` | string | no | URL-safe name, e.g. `base`. Resolves anywhere `code` resolves. |
| `legacy_id` | string | yes | Alternate string id for the set, e.g. `base1` for `bs`. Null on sets that never had one — most Japanese and Chinese print lines. |
| `name` | string | no | Printed set name. |
| `series` | string | yes | Series name, e.g. `Base`. Null where the series is not mapped. |
| `region` | string | no | `WEST` (176 sets), `JP` (380) or `CN` (96), counted 2026-09-18. `KR` is valid in the schema and matches no rows. The region decides which upstream is authoritative and which prices are comparable. |
| `release_date` | date | yes | `YYYY-MM-DD`. The catalogue runs from 1996-10-20 to 2026-09-16. |
| `total` | integer | yes | Cards present in the catalogue, including secret rares but excluding variants such as reverse holos. Null when the set has no cards. |
| `printed_total` | integer | yes | The number printed on the card, e.g. 102 of a 134-card set. |
| `ptcgo_code` | string | yes | Code used by the game client, e.g. `BS`. |
| `symbol_url` | string | yes | Expansion symbol. **Null on every set, without exception** : our upstream carries the logo and not the symbol, so nothing is written here. Use `logo_url`, which is present on all but ten sets (measured 2026-09-17: 641 of 651). (This row read "frequently null" until 2026-09-03, which was a kinder word than the data deserved.) |
| `logo_url` | string | yes | Set logo. |
| `updated_at` | timestamp | no | ISO 8601, UTC. |

### Example


{
  "id": "bs",
  "code": "bs",
  "slug": "base",
  "legacy_id": "base1",
  "name": "Base",
  "series": "Base",
  "region": "WEST",
  "release_date": "1999-01-09",
  "total": 134,
  "printed_total": 102,
  "ptcgo_code": "BS",
  "symbol_url": null,
  "logo_url": "https://media.rarebit.app/sets/BASE/logo-normal.webp",
  "updated_at": "2026-08-26T17:47:39.900Z"
}


### Notes
- Asian print lines are separate sets: a Japanese set is its own set, with its own code, its own numbering and its own release date — not a translation of a Western one. `region` is how you keep the two apart, and `?region=JP` on `/v1/sets` is a real filter that returns 379 rows.
- `lang` on the card endpoints is a different thing entirely: it translates a printed name and does not change which set you are looking at.
```

--------------------------------

### Example response for a sealed product

Source: https://pokemontcgapi.com/docs/api/sealed/get

Example JSON response for a successful request. Shows the product fields including `id`, `sku`, `slug`, `name`, `kind`, `set_code`, `set_name`, `image_url`, `release_date`, `pack_count`, `languages`, `index_eur`, `last_price_at`, `created_at`, and `updated_at`.

```json
{
  "id": "evolving-skies-booster-box",
  "sku": "evolving-skies-booster-box",
  "slug": "evolving-skies-booster-box",
  "name": "Evolving Skies Booster Box",
  "kind": "BOOSTER_BOX",
  "set_code": "evs",
  "set_name": "Evolving Skies",
  "image_url": "https://media.rarebit.app/boxes/evolving-skies-booster-box-normal.webp",
  "release_date": null,
  "pack_count": 36,
  "languages": [],
  "index_eur": 1750,
  "last_price_at": "2026-09-02T00:36:37.317Z",
  "created_at": "2026-05-23T12:43:56.069Z",
  "updated_at": "2026-09-02T15:56:54.473Z"
}
```
Tokens:
Raw