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.

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#

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);

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.

Next steps#