Batch requests

Beta

Fetch many cards in one call, returning the v2 response shape.

POST /v2/cards works like POST /cards in v1: send a JSON array of lookup objects and get many cards back in a single request. Every card comes back in the v2 schema (UUID-first identity and the per-region markets array), not the v1 shape. The maximum array length is the same per-plan limit as v1; see per-request limits.

Body keys are snake_case:v2 batch items use card_id, variant_id, tcgplayer_sku_id and so on. A v1-style item such as {"cardId": "..."} names no identifier and returns a 400.

Lookup items

Each item must name at least one identifier. If an item names several, the most specific one wins, in this order: variant_id, tcgplayer_sku_id, tcgplayer_id, mtgjson_id, scryfall_id, card_id. This is the same rule GET /v2/cards applies.

card_id

uuid | slug

Optional

One card. Accepts a UUID or a legacy v1 slug.

variant_id

uuid | slug

Optional

One variant. A graded variant resolves here too, priced as a slab.

tcgplayer_id

string

Optional

One card by its TCGplayer product ID.

tcgplayer_sku_id

string

Optional

One variant by its TCGplayer SKU ID.

mtgjson_id

string

Optional

One card by its MTGJSON ID.

scryfall_id

string

Optional

One card by its Scryfall ID.

Query parameters

include, updated_after and regions go on the query string and apply to the whole batch, with the same meaning as on GET /v2/cards. A per-item updated_after is rejected with a 400; use the query parameter instead.

Example

request.sh

curl -X POST "https://api.justtcg.com/v2/cards?include=periods.30d" \
  -H "x-api-key: tcg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '[
    { "card_id": "pokemon-base-set-charizard-holo-rare", "condition": "NM" },
    { "tcgplayer_sku_id": "1247795" },
    { "variant_id": "003b8757-d59a-5ec8-baa1-cf14942feed4" }
  ]'

Response

The body is { "data": Card[], "meta": { "count": n } }. Variants are grouped under their card, so two items that name variants of the same card return one card. Items that match nothing are left out without an error, and duplicates collapse. meta.count counts the cards in data, not the items you sent, so do not use it as a completeness check: compare the returned IDs against your request instead.

Graded cards in batch:Batch returns a graded variant only when it already has a price, for example when you name it by variant_id. It does not accept graded, grading_company or grade. To request a specific grade, use a direct lookup.