Pagination

V3 list endpoints use the same pagination shape across the surface:

Param	Type	Default	Range
limit	int	varies per endpoint, typically 20	0..100
offset	int	0	>= 0

Every list response includes a totalCount:

{
  "auctions": [ /* up to limit */ ],
  "totalCount": 47
}

Use totalCount to render pagination controls (page indicators, “showing 20 of 47”, etc.) and to know when to stop fetching the next page.

Empty results

A request whose offset >= totalCount returns 200 with an empty array and the correct counts:

{ "auctions": [], "totalCount": 47 }

Not a 404. Treat the empty array as “you’ve paged past the end.”

Stable sort

Every paginated endpoint has a deterministic order with a unique tiebreaker:

• Notifications: (dateInserted DESC, id DESC)
• My activity: (dateInserted DESC, bid.id DESC)
• My cart: (dateInserted ASC, item.id ASC)
• Auctions: depends on the endpoint’s natural sort + id DESC as the final tiebreaker

This means consecutive page fetches at the same offset return the same rows in the same order, even when other users are inserting new rows in parallel. New rows shift the offset boundary; they don’t reshuffle rows inside an offset.

If you’re surfacing live data (e.g., a notifications screen receiving new rows via Socket.IO), the right strategy is:

1. Render page 0 of the API response on screen-open.
2. On new socket event, prepend the new item to the local list.
3. On scroll, request offset=N where N is the count of pre-existing items the user has seen — not the visible row count (which may include the socket-injected items).

Count-only mode

Some endpoints accept limit=0. That tells the server you only want counts, not rows:

{ "notifications": [], "totalCount": 24, "unreadCount": 7 }

This is significantly cheaper than limit=1 because the server skips the list query, the image join, and the favorites lookup entirely — only the indexed counts run. Use it for badge updates, foreground polling, anything where you don’t actually need to render rows.

Endpoints that support count-only mode call it out in their reference page. Currently:

• GET /v3/bidder/notifications?limit=0 — returns totalCount + unreadCount

Variants by endpoint

Most list endpoints follow the standard shape exactly. A few diverge in useful ways:

/v3/bidder/notifications

• limit=0 count-only mode (above).
• unreadCount is always global — it ignores filter and showRead so the badge stays stable as the user toggles filter chips.

/v3/bidder/my-activity

• Returns a single response with two paginated sub-lists: bids[] and purchases[]. Pagination params apply to both in parallel (offset=20 skips the first 20 of each).
• Includes statusCounts for per-status tile counts (winning / losing / won / lost), aggregated across the full visible set — not paginated.

/v3/bidder/my-cart

• Returns items[] plus a totals object (unpaidAmount, paidAmount, currency). The totals are over the full cart, not just the visible page.

Anti-patterns

• limit=1000 to “get everything.” The hard cap is 100. Servers reject larger values with a 400.
• Walking pages with offset=N*limit and assuming new rows haven’t arrived between page fetches. They might have. Either rely on the stable-sort guarantee + accept that newcomers will appear on the next page, or stream from Socket.IO if you need realtime accuracy.
• Polling limit=20 to detect new entries. Use limit=0 for the count, or join the appropriate Socket.IO room for push notifications (see Realtime).

Reference

Behavior is uniform — see each endpoint’s API reference page for the parameters it accepts.