# Cursor pagination

How list endpoints return pages with limit, after, has_more and next_cursor, and how to walk every page without skipping records.


List endpoints do not use page numbers. Each response carries one batch of records and, when more exist, an opaque cursor that marks the last record returned. Your next request sends that cursor back and gets the batch that follows it.

## Request parameters

| Parameter | In | Behaviour |
| :--- | :--- | :--- |
| `limit` | query | Maximum records in the page. When omitted the server uses 20; anything above 100 is lowered to 100 without an error. |
| `after` | query | The `next_cursor` value from the previous page. Leave it out for the first page. |

Every list operation that declares `PageAfter` in the OpenAPI spec names the parameter `after`. Resource filters such as `status` or `q` combine with these two; see [Filtering and searching](/docs/getting-started/expanding-filtering).

## Response fields

| Field | Type | Meaning |
| :--- | :--- | :--- |
| `data` | array | The records in this page. |
| `has_more` | boolean | `true` when records exist after the last item in `data`. |
| `next_cursor` | string | Present only when `has_more` is `true`. Send it as `after`. |

The customer list returns records newest first, ordered by creation time and then by ID when two share a timestamp. Because the cursor stores the position of the last record rather than a page number, a customer created while you iterate lands ahead of your position: it is never returned twice and never shifts older records onto the next page.

## Example request and response

```bash
curl -sS "$BUSINESS_API/customers?limit=2" \
  -H "Authorization: Bearer $API_KEY"
```

```json
{
  "data": [
    {
      "id": "cus_2kFq8VmZ3xNcR7tLpW4hYb9sDeA",
      "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
      "customer_type": "individual",
      "category": "residential",
      "display_name": "Amélia Cossa",
      "phone": "+258841234567",
      "status": "active",
      "created_at": "2026-11-19T09:05:12.481203Z",
      "updated_at": "2026-11-19T09:05:12.481203Z"
    },
    {
      "id": "cus_2kFq9AbN4yPdS8uMqX5iZc0tEfB",
      "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
      "customer_type": "business",
      "category": "institutional",
      "display_name": "Escola Primária de Malhangalene",
      "status": "active",
      "created_at": "2026-11-19T08:20:00.123456789Z",
      "updated_at": "2026-11-19T08:20:00.123456789Z"
    }
  ],
  "has_more": true,
  "next_cursor": "Y3VzXzJrRnE5QWJONHlQZFM4dU1xWDVpWmMwdEVmQnwxNzk1MDc2NDAwMTIzNDU2Nzg5"
}
```

To fetch the next page, repeat the request with `after=Y3VzXzJrRnE5QWJONHlQZFM4dU1xWDVpWmMwdEVmQnwxNzk1MDc2NDAwMTIzNDU2Nzg5`. Treat the cursor as an opaque string: do not decode it or build one yourself.

## Walk every page

```javascript
let after = "";
let customers = [];
do {
  const url = new URL("$BUSINESS_API/customers");
  url.searchParams.set("limit", "100");
  if (after) url.searchParams.set("after", after);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.API_KEY}` } });
  if (res.status >= 400) throw new Error(`HTTP ${res.status}`);
  const page = await res.json();
  customers = customers.concat(page.data);
  after = page.has_more ? page.next_cursor : "";
} while (after);
```

```python
import os, requests

after = None
customers = []
while True:
    params = {"limit": 100}
    if after:
        params["after"] = after
    res = requests.get(
        "$BUSINESS_API/customers",
        params=params,
        headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    )
    res.raise_for_status()
    page = res.json()
    customers.extend(page["data"])
    if not page["has_more"]:
        break
    after = page["next_cursor"]
```

From the terminal, `gotactl customers list --all` follows the pages for you, and `gotactl api GET business:/customers --paginate` does the same for any list endpoint.

## Pagination errors

A cursor the server cannot decode, which usually means it was edited or copied only in part, is refused with `400` and `error_code: "request.cursor_invalid"`; start again from the first page. On the customer lists, a `limit` that is not a non-negative integer also returns `400`, with `error_code: "request.invalid"`; correct the value and repeat the request. The full error shape is described in [Errors](/docs/getting-started/errors).

## Next steps

- [Filter and search list results](/docs/getting-started/expanding-filtering)
- [Import customers in bulk](/docs/guides/import-customers)
- [Business API reference](/docs/api/business)

