Auto-Pagination

Overview

Search endpoints return paginated results. The SDK provides PaginatedResult<T> which implements AsyncIterable, letting you iterate through all items across all pages without manual page management.

Basic usage

const results = await borough.rentals.search({
  areas: "120",
  minBeds: 1,
  maxPrice: 4000,
});

// Iterate through ALL listings across all pages
for await (const listing of results) {
  console.log(`${listing.address.street} — $${listing.price}`);
}

The iterator automatically fetches the next page when the current page is exhausted.

Collecting results

Use toArray() to collect all items into an array:

// Get all results
const allListings = await results.toArray();

// Get first 100 results (stops fetching after enough items)
const first100 = await results.toArray({ limit: 100 });

Accessing page metadata

The initial response includes pagination metadata:

const results = await borough.rentals.search({ areas: "120" });

console.log(results.meta.total); // Total matching listings
console.log(results.meta.page); // Current page (1-indexed)
console.log(results.meta.perPage); // Items per page
console.log(results.data.length); // Items on this page

Controlling page size

// Smaller pages (fewer items per request)
const results = await borough.rentals.search({
  areas: "120",
  perPage: 10,
});

// Larger pages (Starter: max 50, Pro/Business: max 500)
const results = await borough.rentals.search({
  areas: "120",
  perPage: 500,
});

Example: export all Brooklyn rentals

import { BoroughClient } from "@borough/sdk";

const borough = new BoroughClient("BOROUGH-...");

const results = await borough.rentals.search({
  areas: "300", // Brooklyn
  perPage: 500,
});

const listings = await results.toArray();
console.log(`Exported ${listings.length} Brooklyn rentals`);

// Write to CSV, database, etc.
for (const listing of listings) {
  // process each listing...
}

Rate limit awareness

Auto-pagination respects your tier’s rate limits. If you hit a rate limit during pagination, the SDK automatically retries with backoff. For large exports, consider using a larger perPage value to reduce the number of requests.

Tier	Max perPage	Rate Limit
Free	10	10/min
Starter	50	30/min
Pro	500	60/min
Business	500	120/min