# Pagination

> Walk a collection past the first page with an opaque cursor.

Source: https://api.tailend.dev/docs/pagination

Collections return a cursor; pass it back unchanged to get the next page.

```bash
cursor=""
while :; do
  page=$(curl -sS -H "X-API-Key: $TAILEND_API_KEY" \
    --get "https://api.tailend.dev/v1/philadelphia/events" \
    --data-urlencode "cursor=$cursor")

  echo "$page" | jq '.data[].name'

  cursor=$(echo "$page" | jq -r '.meta.next_cursor // empty')
  [ -z "$cursor" ] && break
done
```

`meta.next_cursor` is `null` once there's nothing left; `meta.has_more` says the same thing without you having to check for `null`.

## What to do

- Treat the cursor as opaque. Don't parse it, store fields out of it, or construct one by hand — a hand-built cursor is a `400`.
- A cursor is bound to the request that issued it: same route, resource, and filters. Change a filter and start the traversal over.
- `/v1/{metro}/around` pages each result group independently — a cursor from one group only advances that group.
- For a traversal that must not miss a row, prefer `changed_since` (sync mode) over browse-mode paging; see the endpoint reference for the exact contract on each collection.