> ## Documentation Index
> Fetch the complete documentation index at: https://qwady.wiki/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-Pagination

> Iterate through all result pages automatically

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

```typescript theme={null}
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:

```typescript theme={null}
// 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:

```typescript theme={null}
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

```typescript theme={null}
// 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

```typescript theme={null}
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    |