Graded cards
BetaGraded 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 control which graded variants come back.
gradedstring
Optional
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.
Default:
excludeexcludeonlyincludegrading_companystring
Optional
Returns every grade from a single grading company. This sets graded to only automatically, unless you also pass graded=include.
PSABGSCGCBCCGBVGSGCgradestring[]
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. See Request cost for the full breakdown.Example
Every PSA 10 for a card, alongside its raw pricing.
request.sh
curl "https://api.justtcg.com/v2/cards?card_id=pokemon-base-set-charizard-4&graded=include&grading_company=PSA&grade=10" \
-H "x-api-key: tcg_your_api_key_here"response.json (excerpt)
{
"id": "d41f-psa10-uuid",
"slug": "pokemon-base-set-charizard-4-psa-10",
"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 }
]
}