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#
curl -sS "$BUSINESS_API/customers?limit=2" \
-H "Authorization: Bearer $API_KEY"
{
"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);
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.