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

# Pagination

> How to page through list endpoints with cursors.

All list endpoints use **cursor-based pagination**. You don't pass page numbers — instead you pass the id of the last row you saw, and we return the next slice.

## Request parameters

| Parameter        | Type    | Default | Max   | Notes                                                                      |
| ---------------- | ------- | ------- | ----- | -------------------------------------------------------------------------- |
| `limit`          | integer | `25`    | `100` | Items per page.                                                            |
| `starting_after` | string  | —       | —     | The id of the last item from the previous page. Omit on the first request. |

## Response shape

```json theme={null}
{
  "data": [ /* … */ ],
  "has_more": true,
  "next_cursor": "cly5..."
}
```

* **`data`** — the page of items, ordered most-recent-first.
* **`has_more`** — `true` if more pages exist after this one.
* **`next_cursor`** — pass this as `starting_after` on the next request. `null` when there is no next page.

## Walking the full list

```bash theme={null}
# Page 1
curl "https://sitevisit.app/api/v1/site-visits?limit=50" \
  -H "Authorization: Bearer sv_live_..."

# Page 2 — use next_cursor from the response above
curl "https://sitevisit.app/api/v1/site-visits?limit=50&starting_after=cly5..." \
  -H "Authorization: Bearer sv_live_..."
```

Keep going until `has_more` is `false`.

## Why cursors, not offsets?

Cursors don't drift when rows are inserted or deleted between requests. Offset pagination (`page=2`) can miss items or return duplicates if data changes mid-walk; cursors stay anchored to a specific row.

## Stable ordering

Rows are ordered by `(created_at desc, id desc)` for most resources, and `(visit_date desc, id desc)` for site visits. The compound order makes cursoring deterministic even when many items share the same timestamp.