Skip to documentation
DOCUMENTATIONAPI referenceProductsLook up a product URL
PRODUCTS / V1

Look up a product URL

Look up a product URL

GET/v1/lookup
Bearer key requiredJSON response
Example requestv1
curl --request GET --max-time 35 \  --url 'https://pokepos-market-api.vercel.app/v1/lookup?url=704860' \  --header "Authorization: Bearer $CARDCOUNTER_API_KEY"
Response illustrative JSON
{  "source": "tcgplayer-public-site",  "sourceUrl": "https://www.tcgplayer.com/product/704860",  "observedAt": "2026-10-04T12:30:00.000Z",  "currency": "USD",  "product": {    "productId": 704860,    "sourceUrl": "https://www.tcgplayer.com/product/704860",    "name": "Example Pokémon card",    "category": {      "id": 3,      "name": "Pokemon"    },    "group": {      "id": 100,      "name": "Example set",      "code": "EXM"    },    "productType": "Cards",    "sealed": false,    "cardNumber": "066/128",    "rarity": "Rare",    "attributes": {      "number": "066/128"    },    "formattedAttributes": {},    "skus": [      {        "skuId": 123,        "condition": "Near Mint",        "variant": "Holofoil",        "language": "English"      }    ],    "marketPrice": 5.45,    "lowestPrice": 3,    "lowestPriceWithShipping": 4.99,    "listingCount": 1,    "sellerCount": 1,    "imageCount": 1,    "imageUrl": "https://tcgplayer-cdn.tcgplayer.com/product/704860_in_1000x1000.jpg"  },  "marketPrices": [    {      "skuId": 123,      "condition": "Near Mint",      "variant": "Holofoil",      "language": "English",      "marketPrice": 5.45,      "lowSalePrice": 3,      "highSalePrice": 8,      "sampleSize": 25,      "calculatedAt": "2026-10-04T12:30:00.000Z"    }  ],  "priceCoverage": {    "requestedSkuIds": [      123    ],    "missingSkuIds": []  },  "marketHistory": {    "range": "quarter",    "variants": [      {        "skuId": 123,        "condition": "Near Mint",        "variant": "Holofoil",        "language": "English",        "averageDailyQuantitySold": 1,        "averageDailyTransactionCount": 1,        "totalQuantitySold": 25,        "totalTransactionCount": 25,        "buckets": [          {            "date": "2026-10-01",            "marketPrice": 5.45,            "quantitySold": 2,            "transactionCount": 2,            "lowSalePrice": 3,            "highSalePrice": 8,            "lowSalePriceWithShipping": 4.99,            "highSalePriceWithShipping": 9.99          }        ]      }    ]  },  "listings": {    "total": 1,    "offset": 0,    "limit": 10,    "sort": "price",    "offers": [      {        "listingId": 456,        "skuId": 123,        "seller": {          "id": "example-seller",          "name": "Example seller",          "ratingPercent": 99,          "sales": "100+",          "direct": false,          "verified": true        },        "condition": "Near Mint",        "variant": "Holofoil",        "language": "English",        "quantity": 2,        "itemPrice": 3,        "shippingPrice": 1.99,        "totalPrice": 4.99,        "currency": "USD",        "listingType": "standard"      }    ]  },  "featuredListing": {    "listingId": 456,    "skuId": 123,    "seller": {      "id": "example-seller",      "name": "Example seller",      "ratingPercent": 99,      "sales": "100+",      "direct": false,      "verified": true    },    "condition": "Near Mint",    "variant": "Holofoil",    "language": "English",    "quantity": 2,    "itemPrice": 3,    "shippingPrice": 1.99,    "totalPrice": 4.99,    "currency": "USD",    "listingType": "standard"  },  "sections": {    "details": {      "status": "ok",      "fetchedAt": "2026-10-04T12:30:00.000Z",      "cacheHit": false    },    "prices": {      "status": "ok",      "fetchedAt": "2026-10-04T12:30:00.000Z",      "cacheHit": false    },    "history": {      "status": "ok",      "fetchedAt": "2026-10-04T12:30:00.000Z",      "cacheHit": false    },    "listings": {      "status": "ok",      "fetchedAt": "2026-10-04T12:30:00.000Z",      "cacheHit": false    },    "spotlight": {      "status": "ok",      "fetchedAt": "2026-10-04T12:30:00.000Z",      "cacheHit": false    },    "image": {      "status": "ok",      "fetchedAt": "2026-10-04T12:30:00.000Z",      "cacheHit": false    }  }}
Example values can change with the source.
REQUEST

Parameters

Pass path parameters in the URL and query parameters after ?.

urlstringrequiredquery

Numeric product ID or tcgplayer.com /product/{id} URL. At least 1 characters.

rangestringquery

History window; aliases normalize to long names in responses. Values: month, quarter, semi-annual, annual, 1m, 3m, 6m, 1y. Default: quarter.

offsetintegerquery

Zero-based index of the first result to return. Range: 0–10000. Default: 0.

limitintegerquery

Maximum number of results to include in this response. Range: 1–100. Default: 50.

sortstringquery

Item-price order; totals including shipping can be out of order. Values: price, none. Default: price.

RESPONSE

Response object

Look up a product URL The root schema is ProductSnapshot.

sourcestringrequired

Always tcgplayer-public-site.

sourceUrlstringrequired

Source product page URL.

observedAtstringrequired

Time this response was assembled; it does not imply all sections were refreshed.

currencystringrequired

Always USD.

productProductrequired

Identity and attributes of the selected product.

marketPricesPrice[] | nullrequired

SKU-level current market price observations.

priceCoveragePriceCoverage | nullrequired

Requested and missing SKU IDs; missing rows are not authoritative zero-price observations.

marketHistoryHistoryData | nullrequired

Price and volume history for the selected range.

listingsListingsData | nullrequired

Current seller listings and pagination data.

featuredListingOffer | nullrequired

Featured seller offer when the source provides one.

sectionsobjectrequired

Availability and fetch status for each snapshot section.

Fields in sections
sections.detailsSectionStatusrequired

Value returned by the market data source.

sections.pricesSectionStatusrequired

Market price observations grouped by SKU.

sections.historySectionStatusrequired

Value returned by the market data source.

sections.listingsSectionStatusrequired

Current seller listings and pagination data.

sections.spotlightSectionStatusrequired

Value returned by the market data source.

sections.imageSectionStatusrequired

Value returned by the market data source.

SCHEMAS

Related objects

Expand a type to inspect its fields.

Product19 fields
productIdintegerrequired

Numeric ID for the exact catalog product.

sourceUrlstringrequired

Source product page URL.

namestringrequired

Display name from the source catalog.

categoryobjectrequired

Product line or category for this result.

Fields in category
category.idinteger | nullrequired

Identifier for this item or seller.

category.namestring | nullrequired

Display name from the source catalog.

groupobjectrequired

Set or group metadata from the source catalog.

Fields in group
group.idinteger | nullrequired

Identifier for this item or seller.

group.namestring | nullrequired

Display name from the source catalog.

group.codestring | nullrequired

Machine-readable status or error code.

productTypestring | nullrequired

Product type reported by the catalog.

sealedbooleanrequired

Whether the product is sealed rather than a single card.

cardNumberstring | nullrequired

Collector number printed on the card.

raritystring | nullrequired

Rarity label reported by the catalog.

attributesobjectrequired

Structured product attributes.

formattedAttributesobjectrequired

Source-formatted product attributes.

skusSku[]required

Conditions, finishes, and languages offered for this product.

marketPricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

lowestPricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

lowestPriceWithShippingnumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

listingCountinteger | nullrequired

Number of current listings, when reported.

sellerCountinteger | nullrequired

Number of current sellers, when reported.

imageCountinteger | nullrequired

Number of source product images when reported.

imageUrlstring | nullrequired

Verified source URL for the product image.

Sku4 fields
skuIdintegerrequired

Numeric ID of one condition and variant combination.

conditionstring | nullrequired

Card condition associated with this SKU or offer.

variantstring | nullrequired

Printing finish or variant associated with this SKU or offer.

languagestring | nullrequired

Language associated with this SKU or offer.

Price9 fields
skuIdintegerrequired

Numeric ID of one condition and variant combination.

conditionstring | nullrequired

Card condition associated with this SKU or offer.

variantstring | nullrequired

Printing finish or variant associated with this SKU or offer.

languagestring | nullrequired

Language associated with this SKU or offer.

marketPricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

lowSalePricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

highSalePricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

sampleSizeinteger | nullrequired

Number of observations used by the source calculation.

calculatedAtstring | nullrequired

Time the source calculated this price.

PriceCoverage2 fields
requestedSkuIdsinteger[]required

SKU IDs requested for this product.

missingSkuIdsinteger[]required

Requested SKU IDs for which the source returned no row.

HistoryData2 fields
rangestringrequired

One of month, quarter, semi-annual, annual.

variantsHistoryVariant[]required

Per-SKU market history series.

HistoryVariant9 fields
skuIdintegerrequired

Numeric ID of one condition and variant combination.

conditionstring | nullrequired

Card condition associated with this SKU or offer.

variantstring | nullrequired

Printing finish or variant associated with this SKU or offer.

languagestring | nullrequired

Language associated with this SKU or offer.

averageDailyQuantitySoldnumber | nullrequired

Average items sold per day in this range.

averageDailyTransactionCountnumber | nullrequired

Average daily transactions reported for the range.

totalQuantitySoldinteger | nullrequired

Total items sold in this range.

totalTransactionCountinteger | nullrequired

Transactions observed in this history range.

bucketsHistoryBucket[]required

Chronological price and sales observations.

HistoryBucket8 fields
datestring | nullrequired

Date of this history bucket.

marketPricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

quantitySoldinteger | nullrequired

Items sold in this history bucket.

transactionCountinteger | nullrequired

Sale transactions in this history bucket.

lowSalePricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

highSalePricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

lowSalePriceWithShippingnumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

highSalePriceWithShippingnumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

ListingsData5 fields
totalinteger | nullrequired

Number of matching results or offers reported by the source.

offsetintegerrequired

Zero-based offset used for this page.

limitintegerrequired

Maximum results requested for this page.

sortstringrequired

One of price, none.

offersOffer[]required

Current seller offers for the selected page.

Offer12 fields
listingIdintegerrequired

Source identifier for this specific offer.

skuIdinteger | nullrequired

Numeric ID of one condition and variant combination.

sellerSellerrequired

Seller identity and reputation metadata.

conditionstring | nullrequired

Card condition associated with this SKU or offer.

variantstring | nullrequired

Printing finish or variant associated with this SKU or offer.

languagestring | nullrequired

Language associated with this SKU or offer.

quantityinteger | nullrequired

Available quantity on this offer.

itemPricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

shippingPricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

totalPricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

currencystringrequired

Always USD.

listingTypestring | nullrequired

Source offer category when reported.

Seller6 fields
idstring | nullrequired

Identifier for this item or seller.

namestring | nullrequired

Display name from the source catalog.

ratingPercentnumber | nullrequired

Seller rating percentage, when available.

salesstring | number | nullrequired

Source-formatted seller sales count.

directbooleanrequired

Whether the offer participates in source direct fulfillment.

verifiedbooleanrequired

Whether the source marks this seller as verified.

SectionStatus5 fields
statusstringrequired

One of ok, stale, unavailable.

fetchedAtstring

Time this section was fetched, in ISO 8601 format.

cacheHitboolean

Whether a cached observation was served. Read fetchedAt and stale together.

codestring

Machine-readable status or error code.

upstreamStatusinteger | null

HTTP status reported by an upstream source, when known.

HTTP

Status codes

200

Look up a product URL

400

Check route parameters or the JSON body.

401

Account-backed key is invalid, inactive, expired or revoked.

404

Unknown route.

405

Use the method published for this route.

429

Quota or admission limit; inspect error.code and Retry-After.

500

Request failed; preserve x-request-id for support.

502

The source returned an error. Source 404 may map to API 404.

503

Account access store is unavailable or misconfigured.

504

Source request exceeded its budget.

Errors use error.code and error.message. Keep x-request-id for tracing. Read the error code catalog and examples.

Response headers

x-request-id

Request ID for tracing and support.

x-plan

Plan for admitted account-backed requests.

x-ratelimit-limit

Account allowance per UTC minute.

x-ratelimit-remaining

Remaining requests in the UTC minute.

x-monthly-limit

Account allowance per UTC month.

x-monthly-remaining

Remaining requests in the UTC month.

Retry-After

Nonnegative seconds until retry is useful for quota, cooldown or admission failures.

Success, empty, partial, stale and error examples
200 · success
{
  "source": "tcgplayer-public-site",
  "sourceUrl": "https://www.tcgplayer.com/product/704860",
  "observedAt": "2026-10-04T12:30:00.000Z",
  "currency": "USD",
  "product": {
    "productId": 704860,
    "sourceUrl": "https://www.tcgplayer.com/product/704860",
    "name": "Example Pokémon card",
    "category": {
      "id": 3,
      "name": "Pokemon"
    },
    "group": {
      "id": 100,
      "name": "Example set",
      "code": "EXM"
    },
    "productType": "Cards",
    "sealed": false,
    "cardNumber": "066/128",
    "rarity": "Rare",
    "attributes": {
      "number": "066/128"
    },
    "formattedAttributes": {},
    "skus": [
      {
        "skuId": 123,
        "condition": "Near Mint",
        "variant": "Holofoil",
        "language": "English"
      }
    ],
    "marketPrice": 5.45,
    "lowestPrice": 3,
    "lowestPriceWithShipping": 4.99,
    "listingCount": 1,
    "sellerCount": 1,
    "imageCount": 1,
    "imageUrl": "https://tcgplayer-cdn.tcgplayer.com/product/704860_in_1000x1000.jpg"
  },
  "marketPrices": [
    {
      "skuId": 123,
      "condition": "Near Mint",
      "variant": "Holofoil",
      "language": "English",
      "marketPrice": 5.45,
      "lowSalePrice": 3,
      "highSalePrice": 8,
      "sampleSize": 25,
      "calculatedAt": "2026-10-04T12:30:00.000Z"
    }
  ],
  "priceCoverage": {
    "requestedSkuIds": [
      123
    ],
    "missingSkuIds": []
  },
  "marketHistory": {
    "range": "quarter",
    "variants": [
      {
        "skuId": 123,
        "condition": "Near Mint",
        "variant": "Holofoil",
        "language": "English",
        "averageDailyQuantitySold": 1,
        "averageDailyTransactionCount": 1,
        "totalQuantitySold": 25,
        "totalTransactionCount": 25,
        "buckets": [
          {
            "date": "2026-10-01",
            "marketPrice": 5.45,
            "quantitySold": 2,
            "transactionCount": 2,
            "lowSalePrice": 3,
            "highSalePrice": 8,
            "lowSalePriceWithShipping": 4.99,
            "highSalePriceWithShipping": 9.99
          }
        ]
      }
    ]
  },
  "listings": {
    "total": 1,
    "offset": 0,
    "limit": 10,
    "sort": "price",
    "offers": [
      {
        "listingId": 456,
        "skuId": 123,
        "seller": {
          "id": "example-seller",
          "name": "Example seller",
          "ratingPercent": 99,
          "sales": "100+",
          "direct": false,
          "verified": true
        },
        "condition": "Near Mint",
        "variant": "Holofoil",
        "language": "English",
        "quantity": 2,
        "itemPrice": 3,
        "shippingPrice": 1.99,
        "totalPrice": 4.99,
        "currency": "USD",
        "listingType": "standard"
      }
    ]
  },
  "featuredListing": {
    "listingId": 456,
    "skuId": 123,
    "seller": {
      "id": "example-seller",
      "name": "Example seller",
      "ratingPercent": 99,
      "sales": "100+",
      "direct": false,
      "verified": true
    },
    "condition": "Near Mint",
    "variant": "Holofoil",
    "language": "English",
    "quantity": 2,
    "itemPrice": 3,
    "shippingPrice": 1.99,
    "totalPrice": 4.99,
    "currency": "USD",
    "listingType": "standard"
  },
  "sections": {
    "details": {
      "status": "ok",
      "fetchedAt": "2026-10-04T12:30:00.000Z",
      "cacheHit": false
    },
    "prices": {
      "status": "ok",
      "fetchedAt": "2026-10-04T12:30:00.000Z",
      "cacheHit": false
    },
    "history": {
      "status": "ok",
      "fetchedAt": "2026-10-04T12:30:00.000Z",
      "cacheHit": false
    },
    "listings": {
      "status": "ok",
      "fetchedAt": "2026-10-04T12:30:00.000Z",
      "cacheHit": false
    },
    "spotlight": {
      "status": "ok",
      "fetchedAt": "2026-10-04T12:30:00.000Z",
      "cacheHit": false
    },
    "image": {
      "status": "ok",
      "fetchedAt": "2026-10-04T12:30:00.000Z",
      "cacheHit": false
    }
  }
}
400 · INVALID_INPUT
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Check route parameters or the JSON body."
  }
}
401 · INVALID_API_KEY
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Account-backed key is invalid, inactive, expired or revoked."
  }
}
401 · UNAUTHORIZED
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "The optional local single-key credential is missing or invalid."
  }
}
404 · NOT_FOUND
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Unknown route."
  }
}
404 · IMAGE_NOT_AVAILABLE
{
  "error": {
    "code": "IMAGE_NOT_AVAILABLE",
    "message": "No source image is available for this product."
  }
}
405 · METHOD_NOT_ALLOWED
{
  "error": {
    "code": "METHOD_NOT_ALLOWED",
    "message": "Use the method published for this route."
  }
}
429 · RATE_LIMITED
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Minute allowance exhausted; use Retry-After."
  }
}
429 · MONTHLY_QUOTA_EXCEEDED
{
  "error": {
    "code": "MONTHLY_QUOTA_EXCEEDED",
    "message": "Monthly allowance exhausted; retry after the next UTC month."
  }
}
429 · AUTH_RATE_LIMITED
{
  "error": {
    "code": "AUTH_RATE_LIMITED",
    "message": "Authentication admission limit reached."
  }
}
429 · DIAGNOSTIC_RATE_LIMITED
{
  "error": {
    "code": "DIAGNOSTIC_RATE_LIMITED",
    "message": "Usage diagnostic rate limit reached."
  }
}
500 · INTERNAL_ERROR
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Request failed; preserve x-request-id for support."
  }
}
502 · UPSTREAM_HTTP_status
{
  "error": {
    "code": "UPSTREAM_HTTP_503",
    "message": "The source returned an error. Source 404 may map to API 404."
  }
}
502 · UPSTREAM_INVALID_RESPONSE
{
  "error": {
    "code": "UPSTREAM_INVALID_RESPONSE",
    "message": "Source data failed response or identity validation."
  }
}
502 · UPSTREAM_RESPONSE_TOO_LARGE
{
  "error": {
    "code": "UPSTREAM_RESPONSE_TOO_LARGE",
    "message": "Source or aggregate API response exceeds the byte limit."
  }
}
502 · UPSTREAM_NETWORK_ERROR
{
  "error": {
    "code": "UPSTREAM_NETWORK_ERROR",
    "message": "Source transport failed."
  }
}
502 · UPSTREAM_CANCELED
{
  "error": {
    "code": "UPSTREAM_CANCELED",
    "message": "Source work was canceled."
  }
}
503 · ACCESS_STORE_UNAVAILABLE
{
  "error": {
    "code": "ACCESS_STORE_UNAVAILABLE",
    "message": "Account access store is unavailable or misconfigured."
  }
}
503 · USAGE_UNAVAILABLE
{
  "error": {
    "code": "USAGE_UNAVAILABLE",
    "message": "Usage diagnostics require account-backed mode."
  }
}
503 · SERVICE_BUSY
{
  "error": {
    "code": "SERVICE_BUSY",
    "message": "Service admission capacity exhausted; use Retry-After."
  }
}
503 · ACCESS_BUSY
{
  "error": {
    "code": "ACCESS_BUSY",
    "message": "Database authorization capacity exhausted; use Retry-After."
  }
}
503 · UPSTREAM_BUSY
{
  "error": {
    "code": "UPSTREAM_BUSY",
    "message": "Source queue is full; use Retry-After."
  }
}
503 · OCR_BUSY
{
  "error": {
    "code": "OCR_BUSY",
    "message": "Photo recognition queue is full; use Retry-After."
  }
}
503 · OCR_UNAVAILABLE
{
  "error": {
    "code": "OCR_UNAVAILABLE",
    "message": "Photo recognition is unavailable."
  }
}
504 · UPSTREAM_TIMEOUT
{
  "error": {
    "code": "UPSTREAM_TIMEOUT",
    "message": "Source request exceeded its budget."
  }
}
504 · OCR_TIMEOUT
{
  "error": {
    "code": "OCR_TIMEOUT",
    "message": "Photo recognition exceeded its processing budget."
  }
}
504 · REQUEST_DEADLINE_EXCEEDED
{
  "error": {
    "code": "REQUEST_DEADLINE_EXCEEDED",
    "message": "Total request deadline exceeded."
  }
}