How to Paginate Results

The Chainabit API supports two pagination strategies: offset-based and cursor-based. This guide shows how to use both and iterate through complete result sets.

Setup

export TOKEN="your-access-token"

---

Offset-Based Pagination

Use the limit and offset query parameters to navigate through pages by position.

Request

curl -s "https://api.chainabit.com/api/v1/ai/sessions?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "data": [
    { "id": "sess_01HQA...", "title": "Developer Pipeline" },
    { "id": "sess_01HQB...", "title": "Research Assistant" }
  ],
  "meta": {
    "total": 47,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Parameters

Parameter	Type	Default	Description
limit	integer	20	Number of items per page (max 100)
offset	integer	0	Number of items to skip

Check for More Pages

Use the meta.hasNextPage field to determine whether another page exists. Advance the offset by the limit value:

# Page 1
curl -s "https://api.chainabit.com/api/v1/ai/sessions?limit=20&offset=0" -H "Authorization: Bearer $TOKEN"

# Page 2
curl -s "https://api.chainabit.com/api/v1/ai/sessions?limit=20&offset=20" -H "Authorization: Bearer $TOKEN"

# Page 3
curl -s "https://api.chainabit.com/api/v1/ai/sessions?limit=20&offset=40" -H "Authorization: Bearer $TOKEN"

Iterate Through All Pages

OFFSET=0
LIMIT=20
HAS_NEXT=true

while [ "$HAS_NEXT" = "true" ]; do
  RESPONSE=$(curl -s "https://api.chainabit.com/api/v1/ai/sessions?limit=$LIMIT&offset=$OFFSET" \
    -H "Authorization: Bearer $TOKEN")

  # Process the current page
  echo "$RESPONSE" | jq '.data[] | .title'

  # Check for next page
  HAS_NEXT=$(echo "$RESPONSE" | jq -r '.meta.hasNextPage')
  OFFSET=$((OFFSET + LIMIT))
done

---

Cursor-Based Pagination

Some endpoints use cursor-based pagination for more efficient traversal of large or frequently changing datasets. Instead of an offset, you pass an opaque cursor token.

Request

curl -s "https://api.chainabit.com/api/v1/billing/invoices?limit=25" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "data": [
    { "id": "inv_01HQS...", "status": "paid" },
    { "id": "inv_01HQT...", "status": "paid" }
  ],
  "meta": {
    "limit": 25,
    "nextCursor": "eyJpZCI6InNlc3Npb25fMDFIUVQuLi4ifQ==",
    "hasNextPage": true
  }
}

Parameters

Parameter	Type	Default	Description
limit	integer	25	Number of items per page (max 100)
cursor	string	(none)	Cursor token from a previous response

Fetch the Next Page

Pass the nextCursor value as the cursor parameter:

curl -s "https://api.chainabit.com/api/v1/billing/invoices?limit=25&cursor=eyJpZCI6Imludl8wMUhRVC4uLiJ9" \
  -H "Authorization: Bearer $TOKEN"

Iterate Through All Pages

CURSOR=""
HAS_NEXT=true

while [ "$HAS_NEXT" = "true" ]; do
  if [ -z "$CURSOR" ]; then
    URL="https://api.chainabit.com/api/v1/billing/invoices?limit=25"
  else
    URL="https://api.chainabit.com/api/v1/billing/invoices?limit=25&cursor=$CURSOR"
  fi

  RESPONSE=$(curl -s "$URL" -H "Authorization: Bearer $TOKEN")

  # Process the current page
  echo "$RESPONSE" | jq '.data[] | .title'

  # Check for next page
  HAS_NEXT=$(echo "$RESPONSE" | jq -r '.meta.hasNextPage')
  CURSOR=$(echo "$RESPONSE" | jq -r '.meta.nextCursor // empty')
done

---

Choosing a Strategy

	Offset-based	Cursor-based
Jump to a specific page	Yes	No
Stable during concurrent inserts	No (items can shift)	Yes
Performance on large datasets	Slower at high offsets	Consistent
Use when	Small datasets, random page access	Large or real-time datasets

If an endpoint supports both strategies, cursor-based pagination is recommended for production workloads.