# Pagination

List endpoints follow a single, predictable shape: a wrapped envelope
whose `data` payload is `{items: [...], total, limit, offset}` (some
endpoints rename `items` to `accounts`, `notifications`, etc., but the
fields are always present).

### Query parameters

| Parameter | Type | Default | Range | Notes |
|-----------|------|---------|-------|-------|
| `limit` | integer | 50 | 1–1000 | Hard agent-side cap to avoid runaway scans. |
| `offset` | integer | 0 | ≥ 0 | Zero-indexed; combine with `limit` for paging. |
| `sort` | string | endpoint-specific | endpoint-specific | Typed enum on the server (regex-validated). |
| `order` | string | `asc` | `asc`, `desc` | |

### Response shape

```json
{
  "status": "success",
  "data": {
    "items":   [ /* item objects */ ],
    "total":   1245,
    "limit":   50,
    "offset":  0
  }
}
```

For partner integrations that need consistent crawl semantics, page
forwards using `offset += limit` until `len(items) < limit`. WHost
does not currently expose cursor-based pagination; it will be added
under `/api/v2/` if it ever becomes necessary.

---