Pagination

​

Request parameters

​

Response envelope

{
  "items": [
    { "id": "V1StGXR8Z5jdHi6BmyTxQ", "name": "Acme Plumbing" }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA3LTA4In0"
}

• items — the page of results, in the endpoint’s documented order.
• nextCursor — pass as cursor to fetch the next page. null means you have the last page.

​

Iterating all pages

cursor=""
while :; do
  response=$(curl -s "https://api.cactal.ai/v1/websites?limit=100${cursor:+&cursor=$cursor}" \
    -H "Authorization: Bearer $CACTAL_API_KEY")
  echo "$response" | jq -r '.items[].name'
  cursor=$(echo "$response" | jq -r '.nextCursor // empty')
  [ -z "$cursor" ] && break
done

const baseUrl = 'https://api.cactal.ai/v1'
const headers = { Authorization: `Bearer ${process.env.CACTAL_API_KEY}` }

let cursor: string | null = null
do {
  const params = new URLSearchParams({ limit: '100' })
  if (cursor) params.set('cursor', cursor)
  const response = await fetch(`${baseUrl}/websites?${params}`, { headers })
  const page = await response.json()
  for (const website of page.items) console.log(website.name)
  cursor = page.nextCursor
} while (cursor)

​

Rules and edge cases

• Cursors are tied to the endpoint and its sort mode. Changing sort or filters invalidates a cursor — start over without one.
• An invalid or corrupted cursor returns 400 validation. Restart from the first page.
• Pages are stable against inserts and deletes: keyset pagination never skips or duplicates items because of concurrent writes elsewhere in the list.
• Treat nextCursor: null as the only end-of-list signal. A short page is not one — a page can legally hold fewer than limit items.

​

Endpoints that differ

• CMS items (GET /v1/cms/collections/{collectionId}/items) additionally supports 1-based page offsets as an alternative to cursor (the two are mutually exclusive) and returns { items, nextCursor, nextPage }. It also accepts filter, search, sort, and depth — see the endpoint page.
• Fixed-cardinality reads return plain objects or arrays with no envelope, because a product rule caps how many results can exist: website domains (one platform domain plus your custom-domain quota), CMS collection fields (a per-collection field limit), notification preferences (a fixed category catalog), and analytics (explicit top-N and max-points limits, with truncation reported in the response).