All list endpoints in the SpeyBooks API return paginated results. Pagination uses a simple page-based model with consistent parameters and response metadata across every resource.
Request parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | The page number to retrieve. Must be 1 or greater. |
perPage | integer | 50 | The number of items per page. Minimum 1, maximum 100. |
Pass these as query parameters:
GET /api/v1/invoices?page=2&perPage=25
Response format
Paginated responses include a meta object alongside the data.
| Field | Type | Description |
|---|---|---|
page | integer | The current page number |
perPage | integer | The number of items per page |
total | integer | The total number of items across all pages |
pages | integer | The total number of pages |
Iterating through pages
To retrieve all items, increment page until it exceeds meta.pages:
let page = 1;
let allInvoices = [];
while (true) {
const res = await fetch(
`https://api.speybooks.com/v1/invoices?page=${page}&perPage=100`,
{ headers: { "Authorization": `Bearer ${apiKey}` } }
);
const json = await res.json();
allInvoices.push(...json.data.invoices);
if (page >= json.meta.pages) break;
page++;
}
Sorting and filtering
Many list endpoints support additional query parameters for sorting and filtering. These are documented on each endpoint's individual page. Common patterns include status, sort, order (asc or desc), date range via from and to (ISO 8601), and search for text search.
Empty results
When no items match, the response returns an empty array with total: 0.
Rate limiting
Paginated requests count as individual API calls against your rate limit. If you need to retrieve large datasets, use perPage=100 to minimise the number of requests.