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

# Pagination

> Cursor-based pagination for list endpoints.

List endpoints return at most **10 records per page by default**
(maximum **100**). Pagination is **cursor-based**; there are no page
numbers, and the cursor is opaque.

## Query parameters

| Name     | Type    | Default | Max   | Notes                                                               |
| -------- | ------- | ------- | ----- | ------------------------------------------------------------------- |
| `cursor` | string  | none    | n/a   | Pass back what you got in `next_cursor` from the previous response. |
| `limit`  | integer | `10`    | `100` | Must be `>= 1`. Values above `100` return `422`.                    |

## Response shape

```json theme={null}
{
  "data": [
    { /* …record… */ },
    { /* …record… */ }
  ],
  "next_cursor": "eyJpZCI6MTIzfQ=="
}
```

* `data`: the page of records.
* `next_cursor`: pass back to fetch the next page. `null` on the
  last page; that's how you know you're done.

## Walking a list

```bash theme={null}
cursor=""
while :; do
  resp=$(curl -s -G https://api.kwugwo.africa/v1/ugwo \
    -H "Authorization: Bearer $KWUGWO_SECRET_KEY" \
    --data-urlencode "limit=50" \
    --data-urlencode "cursor=$cursor")

  echo "$resp" | jq -c '.data[]'

  cursor=$(echo "$resp" | jq -r '.next_cursor')
  [ "$cursor" = "null" ] && break
done
```

## What you cannot do

* Jump to a specific page.
* Walk a list backwards.
* Use a cursor with a different `limit` than the page it came from
  (this works in practice, but is not contract; don't rely on it).