# Pagination

> HubFit API lists are cursor-paginated. Pass nextCursor back as cursor to fetch the next page, and read totalCount for how many match.

Source: https://hubfit.com/developers/pagination

## How it works

A list returns a page of results in `data`, newest first unless the endpoint says otherwise, with `nextCursor` and `totalCount`.

- `limit`: how many results a page holds, from 1 to 100. The default is 25.
- `nextCursor`: pass it back as `cursor` to get the next page. It's `null` on the last page.
- `totalCount`: how many results match across every page, ignoring `cursor` and `limit`. Counting stops at 10,000, so 10,000 means at least that many.

Cursors are opaque: don't parse or build them, as their length and format can change. Keep the other parameters the same from page to page.

**A page**

```json
{
  "data": ["…"],
  "nextCursor": "eyJpZCI6IjZhZDZhZjNmMjljNTk3ZjE1In0",
  "totalCount": 48
}
```

## Fetching every page

Loop until `nextCursor` is `null`. To compare clients over a period, [client summaries](https://hubfit.com/developers/api/client-summaries) add it up for you in one row per client, so you don't need every record.

**Fetch every client**

Node.js:

```javascript
async function listAll(path, params = {}) {
  const results = [];
  let cursor = null;
  do {
    const query = new URLSearchParams({ ...params, limit: "100", ...(cursor && { cursor }) });
    const response = await fetch(`https://api.hubfit.com/v1${path}?${query}`, {
      headers: { Authorization: `Bearer ${process.env.HUBFIT_API_KEY}` },
    });
    const page = await response.json();
    results.push(...page.data);
    cursor = page.nextCursor;
  } while (cursor);
  return results;
}

const clients = await listAll("/clients");
```

Python:

```python
import os
import requests

def list_all(path, params=None):
    results, cursor = [], None
    while True:
        query = {**(params or {}), "limit": 100, **({"cursor": cursor} if cursor else {})}
        page = requests.get(
            f"https://api.hubfit.com/v1{path}",
            headers={"Authorization": f"Bearer {os.environ['HUBFIT_API_KEY']}"},
            params=query,
        ).json()
        results.extend(page["data"])
        cursor = page["nextCursor"]
        if cursor is None:
            return results

clients = list_all("/clients")
```