Pagination

Lists are divided into pages. The default page size is 50, but this can be adjusted with the limit parameter. The maximum page size is 1000.

Cursors

Cursors are object IDs that define your position in a list. Unlike offset-based pagination, cursors eliminate the possibility of returning duplicate objects and gracefully handle new items as they are added.

Every list resource supports the starting_after, and ending_before parameters. To request the next page, set starting_after to the last object ID in the current page. To request the previous page, set ending_before to the first object ID in the current page.

The List object

Responses containing a record of multiple objects are returned wrapped in the list object.

Example

const firstPage = await bias.customers.list();
const secondPage = await bias.customers.list({
  starting_after: firstPage.items.at(-1).id,
});

Auto-pagination

Sometimes, it may be be necessary to retrieve a large number of objects. For this reason, the SDK provides fetchListPages and iterateListPages utilities to automatically paginate through a list.

// Auto-paginate to array
const customers = await fetchListPages(
	sdk.customers.list,
	{ limit: 1000 }, // Use the maximum limit per page
	{ maxItems: 10000 } // Fetch up to 10,000 customers (10 pages) in total
);

// Auto-paginate to iterator
const iterator = iterateListPages(sdk.customers.list, { limit: 100 });
for await (const customer of iterator) {
	if (condition) break;
	// Do something with the customer
}