---
title: "Graded cards — JustTCG API v2"
description: "How PSA, BGS, CGC and other graded cards fit into the /v2/cards response as first-class variants, and how to request them with graded, grading_company and grade."
url: https://justtcg.com/docs/api/cards-v2/graded
markdown_url: https://justtcg.com/docs/api/cards-v2/graded.md
---

# Graded cards

Beta

Graded cards (PSA, BGS, CGC, and more) are one of the biggest additions in v2.

Graded cards are simple to work with: they are just **extra entries in the same `variants` array**, not a separate resource. A `type` field tells the two kinds apart, and the table below shows how each kind fills in `condition` and `grading`. Graded cards are **off by default** (`graded=exclude`), so moving from v1 to v2 gives you the same raw-only results you had before.

## Raw vs. graded

| type | condition | grading |
| --- | --- | --- |
| "raw" | A condition, such as "Near Mint" | null |
| "graded" | null | A populated grading object |

## The `grading` object

Present only when `type` is `"graded"`, and `null` otherwise. Each distinct combination of company, grade, and qualifier is its own **variant**, with its own `id` and `markets`.

| Property | Type | Description |
| --- | --- | --- |
| company | string | The grading company. One of PSA, BGS, CGC, BCCG, BVG, or SGC. |
| grade | number \| null | The numeric grade, such as 9 or 10. This is null only for cards graded "Authentic". |
| grade\_label | string \| null | A special designation such as "Black Label" or "Pristine", when one applies. Otherwise null. |
| qualifier | string \| null | A grading qualifier such as "OC" for off-center. Cards with a qualifier are priced separately. Otherwise null. |
| canonical | string | A ready-to-display grade string, such as "PSA 10". |

## Requesting graded cards

Three query parameters on [/v2/cards](https://justtcg.com/docs/api/cards-v2) control which graded variants come back.

**`graded`** · string · Optional · Default: `exclude` · Values: `exclude`, `only`, `include`

Controls which kinds of variants come back: exclude for raw only, only for graded only, or include for both. Note that \`include\` adds a graded surcharge.

**`grading_company`** · string · Optional · Values: `PSA`, `BGS`, `CGC`, `BCCG`, `BVG`, `SGC`

Returns every grade from a single grading company. This sets graded to only automatically, unless you also pass graded=include.

**`grade`** · string[] · Optional

Narrows the results to specific grades within the chosen company, for example 9.5,10.

**Request cost:** Requesting graded cards on their own (`graded=only`) costs the same as an equivalent v1 call. Requesting raw **and** graded variants together (`graded=include`) adds a surcharge at general availability. During the beta the surcharge is not applied. See [Request cost](https://justtcg.com/docs/api/cards-v2#v2-cost) for the full breakdown.

## Example

Every PSA 10 for a card, alongside its raw pricing.

```bash
curl "https://api.justtcg.com/v2/cards?card_id=pokemon-base-set-charizard-holo-rare&graded=include&grading_company=PSA&grade=10" \
  -H "x-api-key: tcg_your_api_key_here"
```

```json
{
  "id": "d41f-psa10-uuid",
  "slug": "d41f-psa10-uuid",
  "type": "graded",
  "condition": null,
  "grading": {
    "company": "PSA", "grade": 10, "grade_label": null,
    "qualifier": null, "canonical": "PSA 10"
  },
  "markets": [
    { "region": "NA", "currency": "USD", "price": 4570.00, "updated_at": 1765630000 }
  ]
}
```