Pagination

List endpoints paginate in one of two ways. Endpoints you walk end-to-end — inventory, listings, sales, the feed changelog — use cursor pagination. Catalogue endpoints you browse or search — POST /v1/products/search, GET /v1/games/{gameId}/expansions — use offset pagination. Each operation's reference page says which it uses.

Cursor pagination

Pass the cursor from a previous response to fetch the next page:

curl "https://public-api.cardnexus.com/v1/inventory?limit=100&cursor=eyJpZCI6IjY1ZjNhMmIxYzhkNGU5ZjdhNmI1YzRkMyJ9" \
  -H "Authorization: Bearer cnk_live_..."

Query param	Default	Max	Notes
`limit`	50	100	Number of items in the page.
`cursor`	—	—	Opaque string from a previous response's `pagination.nextCursor`. Omit on the first call.

The response wraps the page in a stable envelope:

{
  "data": [
    { "id": "65f3a2b1c8d4e9f7a6b5c4d3", "productId": 50212, "quantity": 4 }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6IjY1ZjNhMmI1MjY2YjE1MjY2YjE1MjY2In0"
  }
}

Field	Meaning
`data`	The page. Always an array; empty when there's nothing to return.
`pagination.nextCursor`	Opaque cursor for the next page. `null` on the last page.

Walking every page:

let cursor: string | null = null
do {
  const res = await fetch(
    `https://public-api.cardnexus.com/v1/inventory?limit=100${cursor ? `&cursor=${cursor}` : ""}`,
    { headers: { Authorization: `Bearer ${apiKey}` } },
  )
  const page = await res.json()
  for (const item of page.data) {
    process(item)
  }
  cursor = page.pagination.nextCursor
} while (cursor)

The cursor is opaque — don't decode it, don't construct one yourself, don't assume its format is stable. Treat it as a server-provided token and pass it back verbatim.

Cursor pages are stable under writes: items created or deleted while you walk don't shift the pages you haven't fetched yet, so you never see an item twice or skip one because the set moved underneath you.

Offset pagination

Catalogue search and expansion lists page by position instead, so you can jump to any page and show totals in a UI:

curl "https://public-api.cardnexus.com/v1/games/pokemon/expansions?limit=50&offset=100" \
  -H "Authorization: Bearer cnk_live_..."

Query param	Default	Max	Notes
`limit`	50	200	Number of items in the page.
`offset`	0	—	How many items to skip from the start of the result set.

{
  "data": [
    { "id": 87, "name": "Surging Sparks", "code": "SSP" }
  ],
  "pagination": {
    "offset": 100,
    "limit": 50,
    "total": 184,
    "hasMore": true
  }
}

Field	Meaning
`data`	The page.
`pagination.offset` / `pagination.limit`	The position and size you asked for.
`pagination.total`	Size of the filtered result set, not the whole catalogue.
`pagination.hasMore`	Whether items exist past this page.

Filtering

Most list endpoints accept query parameters that narrow the result set — for example GET /v1/inventory takes game, productId, forSale, condition, language, finish, graded, and customId filters. Supported filters are listed per endpoint in the API reference.

Filters apply before pagination: pagination.nextCursor (or total) walks the filtered set, not the full collection.

Error handling

Webhooks

Pagination

Cursor pagination

Offset pagination

Filtering

Related