Skip to main content

Pagination

Smart EPD v2 list endpoints use cursor-based pagination. Cursors avoid the page-drift problems of offset/page numbers when rows are appended while you iterate. One caveat applies to rows sharing an identical creation timestamp — see Ordering.

Request parameters​

Query paramTypeDefaultNotes
limitint25Page size. Clamped server-side to 1–100 — values outside the range are pulled to the nearest bound rather than rejected.
cursorstring(none)Opaque cursor from a previous response's next_cursor. Omit it (or send empty) to fetch the first page. Treat the value as a black box — don't construct or parse it.

Response shape​

Every paginated endpoint returns the same envelope:

{
  "data": [ /* the page of items */ ],
  "next_cursor": "MjAyNi0wNS0yOFQxMjowMDowMFo=",
  "has_more": true
}
KeyTypeMeaning
dataarrayThe current page of items.
next_cursorstring | nullPass this as cursor on the next request to get the following page. null on the last page.
has_morebooltrue if at least one more page exists. When false, next_cursor is null and you've reached the end.

Iterating to the end​

Loop until has_more is false (equivalently, until next_cursor is null):

cursor=""
while : ; do
  page=$(curl -s -H "Authorization: Bearer $TOKEN" \
    "https://sandbox.smartepd.xyz/api/v2/projects/$PROJECT_ID/epds/?limit=50&cursor=$cursor")

  echo "$page" | jq -c '.data[]'          # ... process this page ...

  [ "$(echo "$page" | jq -r '.has_more')" = "true" ] || break
  cursor=$(echo "$page" | jq -r '.next_cursor')
done

Ordering​

Results are returned by creation time, oldest first. The cursor encodes the last item's created_at, and the next page fetches rows strictly after it (created_at__gt).

caution

The cursor advances on created_at alone (there is no unique tiebreaker today), so rows that share the exact same created_at tick can straddle a page boundary and be skipped — most likely with bulk- or seed-created data written in the same instant. For exact, gapless iteration over such data, request a generous limit (up to 100) and/or de-duplicate by id on the client. Don't rely on any ordering other than created_at ascending unless an endpoint documents one.

The public EPD library is one that does: it lists newest first by date of issue, and its cursor is gapless.

  • Errors — the error envelope shared by every endpoint.
  • EPD Schema (API) — a worked example that consumes a paginated endpoint.
  • API Quickstart — end-to-end walkthrough including listing resources.