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

# Pagination

> Read every employee page, request totals when needed, and handle live data.

## Choose a page size

Employee search uses one-based page numbers. Start at `page: 1`.

| Operation | Default page size | Maximum page size | Result list |
| - | - | - | - |
| [Search employee profiles](https://help.gowindmill.com/api-reference/employees/search-employee-profiles.md) | 20 | 100 | `employees` |
| [Search employee IDs](https://help.gowindmill.com/api-reference/employees/search-employee-ids.md) | 1,000 | 1,000 | `employeeIds` |

These limits apply to employee search. Check the corresponding reference for [group listing](https://help.gowindmill.com/api-reference/groups/list-readable-employee-groups.md) and other paginated operations.

## Continue while hasMore is true

Search responses include `pagination.page`, `pagination.pageSize`, and `pagination.hasMore`. Keep your filters and sort consistent and increment `page` until `hasMore` is `false`. Empty matches and pages beyond the end return an empty list.

This shell example uses `curl` and `jq`, with the environment variables from [Making requests](https://help.gowindmill.com/api-reference/making-requests.md#read-employee-profiles). It prints one employee object per line:

```bash theme={null}
page=1
while true; do
  body=$(jq -n --argjson page "$page" \
    '{filter:{status:"CURRENT"},sort:{field:"id",direction:"asc"},page:$page,pageSize:100}')

  response=$(curl --fail-with-body --silent --show-error \
    --request POST \
    --url "$WINDMILL_API_BASE/c/$WINDMILL_COMPANY_ID/employees/search" \
    --header "Authorization: Bearer $WINDMILL_API_KEY" \
    --header 'Content-Type: application/json' \
    --data "$body") || break

  printf '%s\n' "$response" | jq -c '.employees[]'
  [ "$(printf '%s\n' "$response" | jq -r '.pagination.hasMore')" = 'true' ] || break
  page=$((page + 1))
  sleep 0.2
done
```

The loop stops on an HTTP error so you can inspect it. For a production job, add [bounded retries](https://help.gowindmill.com/api-reference/errors.md#retry-safely) and [`Retry-After` handling](https://help.gowindmill.com/api-reference/rate-limits#handle-a-429). Coordinate pacing across concurrent workers that share credentials.

### Include archived employees

The filter defaults to `CURRENT`. Change the loop's filter to `status: "FORMER"` for archived employees or `status: "ALL"` for current and former employees. Set `ALL` on nested filters too if they should match archived employees.

## Request totals only when needed

Add `include: { "total": true }` to a search body when you need the total number of matches:

```json theme={null}
{
  "filter": { "status": "ALL" },
  "page": 1,
  "pageSize": 100,
  "include": { "total": true }
}
```

This adds `pagination.total`. Otherwise, `total` is omitted and the extra count is skipped. You don't need a total to iterate: use `hasMore`.

For only a count, use [Count matching employees](https://help.gowindmill.com/api-reference/employees/count-matching-employees.md). Send `{}` when you have no filters. Counts return `{ "total": number }` and don't take page fields.

## Account for changes during a sync

Page pagination reads live data; it doesn't create a snapshot. Employees added, archived, or edited during iteration can move between pages. Sorting by ID gives a consistent ordering for unchanged data, but doesn't provide snapshot or cursor guarantees. Make your sync able to handle repeated IDs and reconcile changes across runs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.