Pagination

List endpoints in the Interstellas API support page-based pagination via page and limit query parameters. Every paginated response includes a top-level pagination object alongside data — but the fields inside that object differ by endpoint. There are two shapes in use across the API; check the endpoint’s own reference page to see which one it returns before you write parsing code against it.

Query parameters

integer

The page number to retrieve. Starts at 1. Defaults to 1 if omitted.

integer

The number of records to return per page. Defaults to 10 or 20 depending on the endpoint — check the endpoint’s reference page.

Example request for page 2 with 25 results per page:

GET /api/v1/clients/members?page=2&limit=25

Shape A — counts and page-existence flags

Used by endpoints such as List members and List disputes:

{
  "status": true,
  "message": "Members retrieved successfully.",
  "data": [...],
  "pagination": {
    "totalCount": 84,
    "hasNextPage": true,
    "hasPreviousPage": true,
    "nextPage": 3,
    "previousPage": 1,
    "limit": 25,
    "lastPage": 4
  }
}

integer

Total number of records matching the current query, across all pages.

boolean

true if more records exist after the current page.

boolean

true if records exist on earlier pages.

integer

Pass this value as ?page= to fetch the next page. Only meaningful when hasNextPage is true.

integer

Pass this value as ?page= to fetch the previous page. Only meaningful when hasPreviousPage is true.

integer

The page size used for this response — reflects your limit parameter or the endpoint’s default.

integer

The final page number, derived from totalCount ÷ limit.

Shape B — current page and totals

Used by endpoints such as List audit logs, List businesses, List customers, List subscriptions, and List virtual accounts:

{
  "status": true,
  "message": "Successful",
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 25,
    "total": 84,
    "totalPages": 4
  }
}

integer

The current page number, echoing your page parameter or its default.

integer

The page size used for this response.

integer

Total number of records matching the current query, across all pages.

integer

The final page number, derived from total ÷ limit.

Some list endpoints — such as List payout accounts — return a plain array with no pagination object at all. Don’t assume one is present; check the endpoint’s reference page.

Iterating all pages

Since the field names differ, write your paging loop against the specific shape the endpoint you’re calling returns. For a Shape A endpoint:

Node.js

async function fetchAllShapeA(url, headers) {
  let page = 1;
  let hasNextPage = true;
  const results = [];

  while (hasNextPage) {
    const res = await fetch(`${url}?page=${page}&limit=50`, { headers });
    const json = await res.json();
    results.push(...json.data);
    hasNextPage = json.pagination.hasNextPage;
    page = json.pagination.nextPage;
  }

  return results;
}

For a Shape B endpoint:

Node.js

async function fetchAllShapeB(url, headers) {
  let page = 1;
  const results = [];

  while (true) {
    const res = await fetch(`${url}?page=${page}&limit=50`, { headers });
    const json = await res.json();
    results.push(...json.data);
    if (page >= json.pagination.totalPages) break;
    page += 1;
  }

  return results;
}

Get started

Essentials

Query parameters

Shape A — counts and page-existence flags

Shape B — current page and totals

Iterating all pages

​Query parameters

​Shape A — counts and page-existence flags

​Shape B — current page and totals

​Iterating all pages

Query parameters

Shape A — counts and page-existence flags

Shape B — current page and totals

Iterating all pages