Generate pagination responses for cursor, offset, page or keyset strategies, with the correctness and performance trade-off of each stated plainly.
Cursor pagination
The server returns an opaque cursor marking where the page ended; the client sends it back for the next page.
A total count is cheap on a small table and expensive on a large one, because the database has to count every matching row — not just the page you asked for.
GET https://api.example.com/v1/orders?limit=25&cursor=eyJpZCI6Iml0bV8wMjUifQContent-Type: application/jsonLink: <https://api.example.com/v1/orders?limit=25&cursor=eyJpZCI6Iml0bV8wNTAifQ>; rel="next"{
"data": [
{
"id": "itm_001",
"name": "Example item 1"
},
{
"id": "itm_002",
"name": "Example item 2"
},
{
"id": "itm_003",
"name": "Example item 3"
}
],
"pagination": {
"nextCursor": "eyJpZCI6Iml0bV8wNTAifQ",
"previousCursor": "eyJpZCI6Iml0bV8wMDEifQ",
"hasMore": true,
"limit": 25
}
}limitHow many items to return.cursorOpaque marker from the previous page's `nextCursor`.API Pagination Designer runs entirely on your device — nothing is uploaded.
You’re on the Free plan. Compare plans
Offset pagination is wrong while the data changes, and that is the decision this tool exists to inform. `LIMIT 25 OFFSET 50` means "skip fifty rows as they are now". Insert a row above the window between two requests and the client sees one item twice; delete one and the client never sees the item that slid past the boundary. Neither produces an error, so it is found months later as a data bug.
It also gets slower the deeper you go. A database serving `OFFSET 100000` counts and discards a hundred thousand rows to return twenty-five. Cursor and keyset pagination turn the same request into an indexed `WHERE` clause, which costs the same on page one thousand as on page one.
People choose offset anyway because it gives a total count and jumpable page numbers, and sometimes the product genuinely needs both. That is a real trade-off rather than a mistake, which is why every strategy here comes with its weaknesses rather than a recommendation.
RFC 8288 `Link` headers are generated alongside the body, because putting the next-page URL in a header is what lets a generic client follow pagination without knowing your body shape. GitHub's API is the best-known example and remains the clearest.
A total count is cheap on a small table and expensive on a large one, since the database has to count every matching row rather than just the page. The option is there, with that cost stated where you turn it on.
Because the offset is counted against the data as it is right now. A row inserted above your window shifts everything down, so the next page repeats an item; a deletion skips one. No error is raised, which is what makes it hard to find.
Mostly whether the client can see the boundary. Keyset exposes the sort key directly; cursor wraps it in an opaque token. The opacity is the point — it lets you change the implementation without breaking clients.
Yes, with a separate count query, and you pay for it on every page. Many APIs return the count only on the first page, or offer it as an opt-in parameter.
Putting the next and previous URLs in a header rather than the body, so a generic client can follow pagination without knowing your body shape. RFC 8288 defines the format; GitHub's API is the familiar example.
Small enough that a page is cheap, large enough that clients are not making hundreds of requests — 20 to 100 for most APIs. The important part is enforcing a maximum, so a client cannot ask for a million rows.