PRODUCTS / V1

Look up a URL

Start with a TCGplayer product URL or ID and receive the same market snapshot as the product endpoint.

GET/v1/lookup

Bearer key requiredJSON response

Example requestv1

01curl --request GET \02  --url 'https://pokepos-market-api.vercel.app/v1/lookup?url=https%3A%2F%2Fwww.tcgplayer.com%2Fproduct%2F704860' \03  --header 'Authorization: Bearer YOUR_API_KEY'

Response illustrative JSON

01{02  "source": "tcgplayer-public-site",03  "sourceUrl": "https://www.tcgplayer.com/product/704860",04  "observedAt": "2026-09-29T12:30:00.000Z",05  "currency": "USD",06  "product": {07    "productId": 704860,08    "name": "Mega Excadrill ex"09  },10  "marketPrices": [],11  "marketHistory": null,12  "listings": null,13  "featuredListing": null,14  "sections": {15    "details": {16      "status": "ok"17    }18  }19}

Example values can change with the source.

REQUEST

Parameters

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

urlstringrequiredquery

A TCGplayer product URL or a numeric product ID. Example: https://www.tcgplayer.com/product/716465.

rangestringquery

One, three, six, or twelve months of recorded history. Values: month, quarter, semi-annual, annual. 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.

RESPONSE

Response object

Full product snapshot. The root schema is ProductSnapshot.

sourcestring

Name of the market data source.

sourceUrlstring

Source product page URL.

observedAtstring

Time the combined product snapshot was observed.

currencystring

Always USD.

productProduct

Identity and attributes of the selected product.

marketPricesPrice[] | null

SKU-level current market price observations.

marketHistoryHistoryResult | null

Price and volume history for the selected range.

listingsListingsResult | null

Current seller listings and pagination data.

featuredListingOffer | null

Featured seller offer when the source provides one.

sectionsobject

Availability and fetch status for each snapshot section.

SCHEMAS

Related objects

Expand a type to inspect its fields.

Product18 fields

productIdinteger

Numeric ID for the exact catalog product.

sourceUrlstring

Source product page URL.

namestring

Display name from the source catalog.

categoryobject

Product line or category for this result.

groupobject

Set or group metadata from the source catalog.

productTypestring | null

Product type reported by the catalog.

sealedboolean

Whether the product is sealed rather than a single card.

cardNumberstring | null

Collector number printed on the card.

raritystring | null

Rarity label reported by the catalog.

attributesobject

Structured product attributes.

formattedAttributesobject

Source-formatted product attributes.

skusSku[]

Conditions, finishes, and languages offered for this product.

marketPricenumber | null

US dollars. Null means no observation is available.

lowestPricenumber | null

US dollars. Null means no observation is available.

lowestPriceWithShippingnumber | null

US dollars. Null means no observation is available.

listingCountinteger | null

Number of current listings, when reported.

sellerCountinteger | null

Number of current sellers, when reported.

imageUrlstring | null

Verified source URL for the product image.

Sku4 fields

skuIdinteger

Numeric ID of one condition and variant combination.

conditionstring | null

Card condition associated with this SKU or offer.

variantstring | null

Printing finish or variant associated with this SKU or offer.

languagestring | null

Language associated with this SKU or offer.

Price9 fields

skuIdinteger

Numeric ID of one condition and variant combination.

conditionstring | null

Card condition associated with this SKU or offer.

variantstring | null

Printing finish or variant associated with this SKU or offer.

languagestring | null

Language associated with this SKU or offer.

marketPricenumber | null

US dollars. Null means no observation is available.

lowSalePricenumber | null

US dollars. Null means no observation is available.

highSalePricenumber | null

US dollars. Null means no observation is available.

sampleSizeinteger | null

Number of observations used by the source calculation.

calculatedAtstring | null

Time the source calculated this price.

HistoryResult6 fields

sourcestring

Name of the market data source.

productIdinteger

Numeric ID for the exact catalog product.

rangestring

Requested history time window.

fetchedAtstring

Time this section was fetched, in ISO 8601 format.

cacheHitboolean

Whether the response used a cached observation.

variantsHistoryVariant[]

Per-SKU market history series.

HistoryVariant7 fields

skuIdinteger

Numeric ID of one condition and variant combination.

conditionstring | null

Card condition associated with this SKU or offer.

variantstring | null

Printing finish or variant associated with this SKU or offer.

languagestring | null

Language associated with this SKU or offer.

averageDailyQuantitySoldnumber | null

Average items sold per day in this range.

totalQuantitySoldinteger | null

Total items sold in this range.

bucketsHistoryBucket[]

Chronological price and sales observations.

HistoryBucket8 fields

datestring | null

Date of this history bucket.

marketPricenumber | null

US dollars. Null means no observation is available.

quantitySoldinteger | null

Items sold in this history bucket.

transactionCountinteger | null

Sale transactions in this history bucket.

lowSalePricenumber | null

US dollars. Null means no observation is available.

highSalePricenumber | null

US dollars. Null means no observation is available.

lowSalePriceWithShippingnumber | null

US dollars. Null means no observation is available.

highSalePriceWithShippingnumber | null

US dollars. Null means no observation is available.

ListingsResult9 fields

sourcestring

Name of the market data source.

productIdinteger

Numeric ID for the exact catalog product.

totalinteger | null

Number of matching results or offers reported by the source.

offsetinteger

Zero-based offset used for this page.

limitinteger

Maximum results requested for this page.

sortstring

Ordering applied to the results.

offersOffer[]

Current seller offers for the selected page.

fetchedAtstring

Time this section was fetched, in ISO 8601 format.

cacheHitboolean

Whether the response used a cached observation.

Offer11 fields

listingIdinteger

Source identifier for this specific offer.

skuIdinteger | null

Numeric ID of one condition and variant combination.

sellerSeller

Seller identity and reputation metadata.

conditionstring | null

Card condition associated with this SKU or offer.

variantstring | null

Printing finish or variant associated with this SKU or offer.

languagestring | null

Language associated with this SKU or offer.

quantityinteger | null

Available quantity on this offer.

itemPricenumber | null

US dollars. Null means no observation is available.

shippingPricenumber | null

US dollars. Null means no observation is available.

totalPricenumber | null

US dollars. Null means no observation is available.

currencystring

Always USD.

Seller6 fields

idstring | null

Identifier for this item or seller.

namestring | null

Display name from the source catalog.

ratingPercentnumber | null

Seller rating percentage, when available.

salesstring | null

Source-formatted seller sales count.

directboolean

Whether the offer participates in source direct fulfillment.

verifiedboolean

Whether the source marks this seller as verified.

SectionStatus5 fields

statusstring

One of ok, unavailable.

fetchedAtstring

Time this section was fetched, in ISO 8601 format.

cacheHitboolean

Whether the response used a cached observation.

codestring

Machine-readable status or error code.

upstreamStatusinteger | null

HTTP status reported by an upstream source, when known.

HTTP

Status codes

200

Full product snapshot.

400

Invalid parameter or request body.

404

Product, route, or image not found.

502

An upstream market source is unavailable.

Errors use the error.code and error.message shape. Keep the x-request-id response header for support and tracing.

PREVIOUSIdentify from image NEXTGet a product snapshot