Pagination

Overview

Borough uses page-based pagination. Pages are 1-indexed (first page is page=1).

Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-indexed), from 1 to 1,000,000. Anything else returns `400`
`perPage`	integer	10	Results per page (max depends on tier)

Pass an explicit perPage (up to your tier max) for larger pages. A perPage above your tier max is not rejected: it is lowered to the max, and meta.perPage and the links reflect the value actually used. Read meta.perPage rather than assuming your requested size was honored.

Response metadata

{
  "data": [...],
  "meta": {
    "total": 342,
    "page": 2,
    "perPage": 50,
    "links": {
      "self": "https://borough.qwady.app/v1/search/rentals?page=2&perPage=50",
      "first": "https://borough.qwady.app/v1/search/rentals?page=1&perPage=50",
      "last": "https://borough.qwady.app/v1/search/rentals?page=7&perPage=50",
      "prev": "https://borough.qwady.app/v1/search/rentals?page=1&perPage=50",
      "next": "https://borough.qwady.app/v1/search/rentals?page=3&perPage=50"
    }
  }
}

total: Total number of matching results across all pages
page: Current page number
perPage: Results per page
links: Navigation URLs for self, first, last, prev (null on first page), and next (null on last page). Present on search and GET /v1/building/{id}/listings; GET /v1/areas is paginated but its meta has no links, so page it with total, page, and perPage

Max perPage by tier

Tier	Max perPage
Free	10
Starter	50
Pro	500
Business	500

SDK auto-pagination

The TypeScript SDK supports automatic pagination via async iterators:

const results = await borough.rentals.search({ areas: '120', perPage: 50 });

// Iterate across pages automatically (up to 100 pages by default)
for await (const listing of results) {
  console.log(listing.address.street);
}

// Or collect into an array with an optional limit
const all = await results.toArray({ limit: 200 });

Every page the SDK fetches is a separate request and costs one unit of quota, so prefer a larger perPage (up to your tier max) over many small pages. Auto-iteration stops at 100 pages by default. If more pages remain at that point, it throws PaginationLimitError (exported by the SDK) rather than silently returning a partial set; at the default perPage of 10, that is any result set over 1,000 items. toArray({ limit }) does not throw when the limit is reached within the cap. Change the cap with the second argument to search:

// Raise the cap, or pass Infinity to remove it
const results = await borough.rentals.search({ areas: '120' }, { maxAutoPages: 500 });

// Or stop quietly at the cap and check whether the scan was cut short
const bounded = await borough.rentals.search({ areas: '120' }, { onMaxAutoPages: 'stop' });
for await (const listing of bounded) { /* ... */ }
if (bounded.truncated) { /* more pages were left unread */ }

Getting Started

Guides

Reference

API Reference

MCP Server

SDK

Overview

Parameters

Response metadata

Max perPage by tier

​Overview

​Parameters

​Response metadata

​Max perPage by tier

​SDK auto-pagination

Overview

Parameters

Response metadata

Max perPage by tier

SDK auto-pagination