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
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"

GET /billing/invoices lists the invoices of the account the request acts in and requires the owner, admin, or billing role in that account.

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
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	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.