# Bulk GET — Total Count Behavior

> **Reference:** [API Consumer Guide — Bulk Operations](https://papidocs.hs1api.com/publicapi/api-consumer-guide#bulk-operations)


## Overview

Bulk GET endpoints return a `pagination` object in every response. This object includes a `total` field representing the total number of records matching your query. The value of `total` — and whether it appears at all — depends on which query parameters are present in your request.

## When You Will See `pagination.total`

### `total` is `0` — Plain bulk GET (default behavior)

When you make a plain bulk GET request without `lastId` or `page`, `total` will be `0`. This means the count was not computed and does **not** indicate that zero records exist.

```
GET /api/v1/appointments?pageSize=500&filter=lastModified>2025-01-01T00:00:00Z
```

```json
{
  "data": [...],
  "pagination": {
    "limit": 500,
    "offset": 0,
    "total": 0
  }
}
```

> Use the `data` array and whether it is empty to determine if more pages are available — do not rely on `total` for this purpose.


### `total` is absent — Cursor pagination with `lastId`

When `lastId` is present in the request, `pagination.total` will **not be present** in the response at all.

```
GET /api/v1/appointments?lastId=8000052360370&pageSize=500&filter=lastModified>2025-01-01T00:00:00Z
```

```json
{
  "data": [...],
  "pagination": {
    "limit": 500,
    "offset": 0
  }
}
```

> This is the recommended pagination pattern. When using `lastId`, you do not need `total` — you continue fetching pages until `data` is empty.


### `total` is absent — Offset pagination with `page`

When the deprecated `page` query parameter is used, `pagination.total` will not be present.

> **Note:** The `page` parameter is deprecated. Use `lastId` pagination instead.


## Behavior Summary

| Request type | `lastId` present | `page` present | `pagination.total` |
|  --- | --- | --- | --- |
| Plain bulk GET | No | No | `0` |
| Cursor pagination | Yes | No | **Field absent** |
| Offset pagination (deprecated) | No | Yes | **Field absent** |


## `pagination` Response Object

| Field | Type | Description |
|  --- | --- | --- |
| `limit` | integer | The page size used for this request |
| `offset` | integer | The record offset applied to this request |
| `total` | integer | Present only when `lastId` and `page` are absent. Returns `0` — the total record count is not computed. |


## Recommendations

**Do not rely on `pagination.total` to determine whether more pages exist.** The reliable signal for end-of-results is an empty `data` array.

**Use `lastId` cursor pagination for all bulk fetches.** This is the most efficient pattern. See the endpoint-specific guides for step-by-step `lastId` pagination instructions.

- [Appointments V1 — Developer Guide](/publicapi/endpoints/appointments-v1)


## Important Notes

> **⚠️ Breaking change for consumers reading `pagination.total`:** If your integration reads `total` to calculate progress or determine whether to continue paginating, you must update your logic. `total` will be `0` for all plain bulk GETs. Use the presence or absence of records in `data` instead.


> **⚠️ Rate Limited:** Bulk GET endpoints are rate limited. See the [rate limiting guide](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting) for details.