Ace Grading Cert Lookup API: Every Field Returned

What the Ace Grading lookup does

The Ace Grading lookup takes the certificate number printed on an ACE slab and returns the record published for it on acegrading.com: the card, the overall grade, the four subgrades, the population counts and the slab photos.

There are two ways to use it:

• The free checker at /ace-checker. No account, 10 lookups a day.
• The API, GET /api/v1/ace/:certNumber, which returns the same record as JSON for your own app, store or inventory tool.

It returns a certificate record. It does not tell you what the slab is worth, and a matching record does not prove that the slab in your hand is genuine. TCGAPIs is independent and is not affiliated with Ace Grading.

Make a request

Send the certificate number in the path and your key in the x-api-key header. This runs on Node 18 or later with no packages.

const cert = '1471772';
const response = await fetch('https://api.tcgapis.com/api/v1/ace/' + cert, {
  headers: { 'x-api-key': process.env.TCGAPIS_KEY },
});
const body = await response.json();
 
if (response.status === 404) {
  console.log('No certificate with that number');
} else if (!response.ok) {
  throw new Error(body.error || 'Lookup failed: ' + response.status);
} else {
  const { certificate } = body;
  console.log(certificate.subject, certificate.grade, certificate.gradeDescription);
  console.log(certificate.subgrades, certificate.population.total);
}

The same request with curl:

curl "https://api.tcgapis.com/api/v1/ace/1471772" \
  -H "x-api-key: INSERT_YOUR_API_KEY_HERE"

To try it without a key, the public demo endpoint is GET /api/v1/ace/demo/:certNumber. It returns the same body and allows 10 lookups per IP address per day.

A full response

This is the record for certificate 1471772, retrieved on 13 November 2026.

{
  "success": true,
  "certificate": {
    "certNumber": "1471772",
    "company": "ACE",
    "subject": "Cetitan ex",
    "set": "Destined Rivals",
    "brand": "Pokemon",
    "game": "Pokemon",
    "year": "2025",
    "cardNumber": "210/182",
    "language": "English",
    "variety": "Secret Rare",
    "labelType": "Ace",
    "grade": 10,
    "gradeDescription": "GEM MINT",
    "subgrades": {
      "centering": 10,
      "corners": 10,
      "edges": 10,
      "surface": 10
    },
    "population": {
      "total": 46,
      "sameGrade": 42,
      "higher": 0,
      "lower": 4,
      "withLabel": 41,
      "gemRate": "91%"
    }
  },
  "images": {
    "front": "https://collectible-images.ams3.cdn.digitaloceanspaces.com/public/collectible/1471772/1471772_front.webp",
    "back": "https://collectible-images.ams3.cdn.digitaloceanspaces.com/public/collectible/1471772/1471772_back.webp",
    "label": "https://ace.ams3.digitaloceanspaces.com/assets/labels/ace/KPmGGcBOzNWhpk5yGdDCxnVTGDvRL0Alwq87HYVz.jpg"
  },
  "viewUrl": "https://acegrading.com/cert/1471772"
}

Every field, explained

The card

All of these sit inside certificate.

• certNumber (string): the certificate number you asked for.
• company (string): always "ACE".
• subject (string): the card name.
• set (string): the set the card belongs to.
• brand (string): the brand on the certificate. Usually the game; on some older certificates it repeats the set series.
• game (string or null): the game, when it could be worked out from the set.
• year (string): the year on the certificate.
• cardNumber (string): the collector number, such as 210/182.
• language (string): the language of the card.
• variety (string): the rarity or variant, such as Secret Rare or Holo.
• labelType (string): the label style.

The grade and subgrades

• certificate.grade (number): the overall grade, such as 10.
• certificate.gradeDescription (string): the grade in words, such as GEM MINT.
• certificate.subgrades.centering (number): the centering subgrade.
• certificate.subgrades.corners (number): the corners subgrade.
• certificate.subgrades.edges (number): the edges subgrade.
• certificate.subgrades.surface (number): the surface subgrade.

grade is a number whenever the certificate shows one. If a certificate ever shows a grade that is not a number, the text is returned as a string instead, so check the type before doing arithmetic with it.

The overall grade is Ace Grading's own decision. It is not an average you can recompute from the four subgrades: the second and third examples below both have a corners subgrade of 9 and an overall grade of 10.

The population

All of these sit inside certificate.population.

• total (number): how many copies of this card Ace Grading has graded.
• sameGrade (number): how many of those received the same grade.
• higher (number): how many were graded higher.
• lower (number): how many were graded lower.
• withLabel (number): how many at this grade carry the same label.
• gemRate (string): the share of copies graded 10, as text such as 91%.

Population counts are captured when the record is retrieved, so they can lag the live Ace Grading page. Treat them as a snapshot. If you need today's count for a sale listing, follow viewUrl.

The photos and the source link

• images.front (string or null): photo of the front of the slab.
• images.back (string or null): photo of the back of the slab.
• images.label (string or null): photo of the label artwork.
• viewUrl (string): the certificate page on acegrading.com.

The image URLs are the ones the Ace Grading certificate page itself uses. Load them directly in an img tag, and plan for them to be missing.

What differs between certificates

Three real certificates, looked up on 13 November 2026, show how much the record varies.

• 1471772: Cetitan ex, Destined Rivals 210/182. Grade 10 GEM MINT. Subgrades: centering 10, corners 10, edges 10, surface 10. Population 46, gem rate 91%. Photos: front, back and label.
• 1000000: Charizard, Skyridge 146/144. Grade 10 GEM MINT. Subgrades: centering 10, corners 9, edges 10, surface 10. Population 25, gem rate 4%. Photos: front, back and label.
• 100003: Penny, Scarlet & Violet 252/198. Grade 10 GEM MINT. Subgrades: centering 10, corners 9, edges 10, surface 10. Population 99, gem rate 35%. Photos: label only.

Things to handle in your code:

• Photos can be missing. Certificate 100003 has no slab photos on record, so images.front and images.back are null. Another certificate we checked had both slab photos but no label photo.
• game can be null. On certificate 100003 it is null, and brand holds "Scarlet & Violet" instead of the game name.
• Any field can be null. The record mirrors the certificate page. If the page does not show a value, the field is null, never an empty string.
• Zero is a real value. population.higher is 0 on all three, meaning no copy has been graded higher. Do not treat 0 as missing.

Status codes

A 404 and a 503 mean different things, and the API keeps them apart. A 404 says the certificate does not exist. A 503 or 504 says we could not find out. Never show "certificate not found" to a customer on a 503.

Speed

Ace Grading lookups are quick. When we tested on 13 November 2026, certificates that had never been requested before were retrieved from the source in about 0.2 to 0.3 seconds, and repeat lookups were answered from memory in a few milliseconds. Your own round trip adds network time on top.

How it compares with the PSA lookup

The PSA checker and its API work the same way but return a different record.

Access and cost

A free account includes 100 one-time credits and needs no payment card. Each successful lookup uses one credit. A lookup that fails or finds nothing gives the credit back.

After the credits, the endpoint is part of the Business plan and above, and each call counts toward the plan's API allowance. Current plans are on the pricing page, and the endpoint reference is in the documentation.

Keep the API key on your server. Do not put it in a web page or a mobile app.

Limits to know

• It returns the certificate record only: no graded-card prices and no sales.
• It does not authenticate a physical slab. Compare the record with the label, and with the photos where they exist.
• Population counts are a snapshot and can lag the live page.
• Only Ace Grading certificate numbers work on this endpoint. For PSA slabs use the PSA endpoint.