---
title: "Batch — JustTCG API v2"
description: "POST /v2/cards fetches many cards in one request: send an array of lookup objects with snake_case identifiers and get every card back in the v2 response schema."
url: https://justtcg.com/docs/api/cards-v2/batch
markdown_url: https://justtcg.com/docs/api/cards-v2/batch.md
---

# Batch requests

Beta

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

`POST /v2/cards` works like [POST /cards](https://justtcg.com/docs/api/cards#post) 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](https://justtcg.com/docs/api/cards-v2) (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](https://justtcg.com/docs/api/cards#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](https://justtcg.com/docs/api/cards-v2). A per-item `updated_after` is rejected with a `400`; use the query parameter instead.

## Example

```bash
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](https://justtcg.com/docs/api/cards-v2/graded).