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

# Pagination

<Danger>
  The Simplifi API is in **Developer Preview**. While not all features are finalised, we encourage you to explore and share your feedback — including thoughts on endpoint design, response structure, or areas where documentation could be clearer.
</Danger>

## Overview

Endpoints that return lists of records are paginated. Rather than returning every matching record in a single response, the API breaks results into pages and provides links to navigate between them.

<Warning>
  The only endpoint that is currently paginated is /timesheets
</Warning>

## Default Page Size

The default page size is **200 records**. If you do not specify a `pageSize`, each response will contain up to 200 records.

## Query Parameters

Control pagination using the following query string parameters:

| Parameter  | Type    | Default | Description                               |
| ---------- | ------- | ------- | ----------------------------------------- |
| `page`     | Integer | `1`     | The page number to retrieve. Starts at 1. |
| `pageSize` | Integer | `200`   | The number of records to return per page. |

### Example Request

```javascript javascript lines theme={null}
const response = await fetch('https://your-instance.simplifi.work/api/timesheets?page=2&pageSize=50', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});
```

## Pagination Response Object

Paginated endpoints return a `pagination` object alongside the data array:

```json javascript lines theme={null}
{
  "data": [ ... ],
  "pagination": {
    "page": 2,
    "pageSize": 50,
    "totalRecords": 340,
    "totalPages": 7,
    "nextPage": "timesheets?page=3&pageSize=50",
    "previousPage": "timesheets?page=1&pageSize=50"
  }
}
```

| Field          | Type    | Description                                                                                                                              |
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `page`         | Integer | The current page number.                                                                                                                 |
| `pageSize`     | Integer | The number of records per page used for this response.                                                                                   |
| `totalRecords` | Integer | The total number of records matching your request.                                                                                       |
| `totalPages`   | Integer | The total number of pages available.                                                                                                     |
| `nextPage`     | String  | The endpoint path for the next page, or omitted if on the last page. Prepend your instance base URL to construct a complete request URL. |
| `previousPage` | String  | The endpoint path for the previous page, or omitted if on page 1. Prepend your instance base URL to construct a complete request URL.    |

## Navigating Pages

The `nextPage` and `previousPage` fields contain endpoint paths that preserve all your existing query parameters (such as date filters). The only change between them is the `page` value.

To construct a full request URL, prepend your instance base URL. To retrieve all records, keep requesting the next page until `nextPage` is no longer present in the response.

```javascript javascript lines theme={null}
const baseUrl = 'https://your-instance.simplifi.work/api/';
let path = 'timesheets';
let allRecords = [];

while (path) {
  const response = await fetch(baseUrl + path, { headers: { Authorization: `Bearer ${token}` } });
  const json = await response.json();
  allRecords = allRecords.concat(json.data);
  path = json.pagination.nextPage || null;
}
```

## Notes

* Page numbers start at **1**. Requesting `page=0` is treated as `page=1`.
* If `pageSize` is not supplied or is `0`, the default of **200** is used.
* Filters such as `dateFrom` and `dateTo` are applied before pagination, so `totalRecords` reflects your filtered result set.
* The `nextPage` and `previousPage` values are endpoint paths, not full URLs. You must prepend your instance base URL (e.g. `https://your-instance.simplifi.work/api/`) to use them in a request.