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

# Pagination

> How to page through list endpoints.

Most list endpoints return a bounded page of results. The
[events](/webhooks/events) timeline is the one you'll page through most, and it
uses **cursor-based** paging by timestamp.

## Cursor paging (events)

`GET /v1/events` returns events in chronological order. To walk the whole
timeline, pass `since=` set to the `occurredAt` of the last event you saw, and
keep going until a page comes back empty.

<CodeGroup>
  ```bash cURL theme={null}
  # First page
  curl "https://api.kuahr.com/v1/events?limit=100" \
    -H "X-Api-Key: kua_live_your_key_here"

  # Next page: since = occurredAt of the last event from the previous page
  curl "https://api.kuahr.com/v1/events?limit=100&since=2026-07-25T10:30:00Z" \
    -H "X-Api-Key: kua_live_your_key_here"
  ```

  ```ts Node theme={null}
  let since: string | undefined = undefined;
  for (;;) {
    const page = await kua.events.list({ since, limit: 100 });
    if (page.length === 0) break;
    for (const event of page) handle(event);
    since = page[page.length - 1].occurredAt;
  }
  ```

  ```python Python theme={null}
  since = None
  while True:
      page = kua.events.list(since=since, limit=100)
      if not page:
          break
      for event in page:
          handle(event)
      since = page[-1].occurred_at
  ```
</CodeGroup>

<Note>
  `limit` accepts **1–500** and defaults to **100**. A page shorter than your
  `limit` means you've reached the end.
</Note>

## Why `since` and not offset

Timestamp cursors are stable as new events arrive — you never skip or double-read
a record the way offset paging can when the underlying list grows between
requests. Persist the last `occurredAt` you processed and resume from it; combined
with deduping on the event `id`, polling becomes safe to restart at any time.