Pagination
Every list endpoint pages by keyset, not by offset. The token is the last row's id, and the next
page seeks past it:
# First page.
curl -H "Authorization: Bearer $AIDE_KEY" 'https://gcaaide.org/api/users?limit=25'
# Next page: pageToken is the last id from the previous response.
curl -H "Authorization: Bearer $AIDE_KEY" \
'https://gcaaide.org/api/users?limit=25&pageToken=01a05f93-53e3-7439-8548-055c5b3e4363'
limit ranges from 1 to 10,000 and defaults to 100.
There is no total
A keyset-paged endpoint deliberately does not report a row count. COUNT(*) over the requests table
on every page load is exactly the cost the cursor exists to avoid, so nothing computes one.
A short page is the last page. That is how a client knows to stop: fewer rows than limit means
there are no more, and paging past the end returns an empty list rather than an error.
Why not offset
An offset re-scans every earlier row on every page, so page 400 costs 400 times page 1. It is also unstable: a row inserted between two requests shifts the window, so a row can appear twice or be skipped entirely. A keyset seek has neither problem, and the ordering column is unique, so there are no ties at a page boundary.
IDs are UUIDv7, which sort by creation time, so ordering by id descending is newest-first and the
cursor reads as a position in time rather than an opaque blob.
Discover pages differently
POST /api/discover/search returns an opaque cursor instead, because startTime alone is not
unique in a table of this size and a page boundary landing mid-second would drop rows. The cursor
encodes (startTime, id).
{
"cursor": "MjAyNi0wMS0yOFQyMzoyMzowMFp8MDE5YzA2ZWEtZDgyMC03NzI5",
"total": 2240,
"truncated": true,
"results": [ ... ]
}
total here is reported, because the histogram computes it as a side effect of drawing itself. It
counts every matching session in the range and does not change as you page, so a count that shrank
while paging would be a bug. truncated says the row limit cut the page short. Absence of cursor
means the last page.
A cursor the server did not issue is a 400, not a 500.