---
title: "/cards — JustTCG API"
description: "GET /cards for direct lookup or search; POST /cards for batch fetches up to 200 cards in one request."
url: https://justtcg.com/docs/api/cards
markdown_url: https://justtcg.com/docs/api/cards.md
---

# /cards

One endpoint, two methods: direct lookup or batch fetch.

**Looking for graded cards?** Try the [/v2/cards](https://justtcg.com/docs/api/cards-v2) beta: PSA, BGS, CGC, and more, as first-class variants.

`GET https://api.justtcg.com/v1/cards`

**`cardId`** · uuid | string · Optional

Direct lookup by card ID.

**`variantId`** · uuid | string · Optional

Direct lookup by variant ID — fastest path.

**`tcgplayerId`** · string · Optional

TCGplayer product ID.

**`mtgjsonId`** · string · Optional

MTGJSON UUID.

**`scryfallId`** · string · Optional

Scryfall UUID.

**`tcgplayerSkuId`** · string · Optional

TCGplayer SKU ID (variant-level).

### Response

```typescript
import { JustTCG } from 'justtcg-js';

const client = new JustTCG();
const { data } = await client.cards.get({
  cardId: 'pokemon-battle-academy-fire-energy-22-charizard-stamped-promo',
  condition: ['NM', 'LP'],
  priceHistoryDuration: '30d',
});

console.log(data[0].variants[0].price);
```

```json
{
  "data": [
    {
      "id": "pokemon-battle-academy-fire-energy-22-charizard-stamped-promo",
      "uuid": "23edc8d4-b6b7-5d0c-a5fa-659040d24a7c",
      "name": "Fire Energy (#22 Charizard Stamped)",
      "game": "Pokemon",
      "set": "battle-academy-pokemon",
      "set_name": "Battle Academy",
      "rarity": "Promo",
      "tcgplayerId": "219042",
      "mtgjsonId": null,
      "scryfallId": null,
      "variants": [
        {
          "id": "pokemon-…_near-mint",
          "uuid": "c6bfa6f7-0b82-5011-b2ee-b572e2708a0e",
          "condition": "Near Mint",
          "printing": "Normal",
          "price": 0.14,
          "priceChange24hr": 0,
          "lastUpdated": 1780936262,
          "priceStatus": "current",
          "lastKnownPrice": null,
          "priceHistory": [{
            "p": 0.14,
            "t": 1780358400
          }]
        }
      ]
    }
  ],
  "meta": { "total": 1, "limit": 20, "offset": 0, "hasMore": false },
  "_metadata": {
    "apiPlan": "Pro",
    "apiRequestsRemaining": 49213
  }
}
```

`POST https://api.justtcg.com/v1/cards`

**Identifier precedence:** `variantId` > `tcgplayerSkuId` > `tcgplayerId` > `mtgjsonId` > `scryfallId` > `cardId`. Use one identifier per item.

**`cardId`** · string · Optional

Card-level lookup.

**`variantId`** · string · Optional

Variant-level lookup — fastest path.

**`tcgplayerId`** · string · Optional

TCGplayer product ID.

**`mtgjsonId`** · string · Optional

MTGJSON UUID.

**`scryfallId`** · string · Optional

Scryfall UUID.

**`tcgplayerSkuId`** · string · Optional

TCGplayer SKU ID.

**Limits:** 200 items / request (Enterprise), 100 (Starter & Pro), 20 (Free). Batch larger workloads.

### Response

```typescript
import { JustTCG } from 'justtcg-js';

const client = new JustTCG();
const { data } = await client.cards.batch([
  { tcgplayerId: '219042', condition: 'NM', printing: 'Normal' },
  { tcgplayerId: '25788',  condition: 'LP', printing: '1st Edition' },
]);
```

```json
{
  "data": [
    {
      "id": "pokemon-battle-academy-fire-energy-22-charizard-stamped-promo",
      "uuid": "23edc8d4-b6b7-5d0c-a5fa-659040d24a7c",
      "name": "Fire Energy (#22 Charizard Stamped)",
      "game": "Pokemon",
      "set": "battle-academy-pokemon",
      "set_name": "Battle Academy",
      "rarity": "Promo",
      "tcgplayerId": "219042",
      "mtgjsonId": null,
      "scryfallId": null,
      "variants": [
        {
          "id": "pokemon-…_near-mint",
          "uuid": "c6bfa6f7-0b82-5011-b2ee-b572e2708a0e",
          "condition": "Near Mint",
          "printing": "Normal",
          "price": 0.14,
          "priceChange24hr": 0,
          "lastUpdated": 1780936262,
          "priceStatus": "current",
          "lastKnownPrice": null,
          "priceHistory": [{
            "p": 0.14,
            "t": 1780358400
          }]
        }
      ]
    }
  ],
  "meta": { "total": 1, "limit": 20, "offset": 0, "hasMore": false },
  "_metadata": {
    "apiPlan": "Pro",
    "apiRequestsRemaining": 49213
  }
}
```

## \*Per-request limits

The maximum number of cards you can request at once depends on your plan. For GET requests this is the highest accepted value for the `limit` parameter; for POST requests it's the maximum length of the lookup array. Batch larger workloads across multiple requests.

| Plan | Max cards per request |
| --- | --- |
| Free | 20 cards |
| Starter | 100 cards |
| Pro | 100 cards |
| Enterprise | 200 cards |