Almost every list in a real application is paginated. A feed, a search result, an order history or a directory of users will eventually hold more records than any single response should carry, so the API hands them out a page at a time. That sounds simple, and the happy path usually works on the first try. The bugs hide at the boundaries: the last page, the empty page, the page that should exist but does not, and the cursor that points one record too far. The API Pagination Test Data Builder exists for exactly this problem. It builds a paginated test dataset in your browser so you can check those boundaries before real users find them.
Pagination comes in two main shapes. Offset pagination asks for a page number and a page size, and the server skips ahead by multiplying the two. Cursor pagination instead hands the client a marker, usually the last item seen, and asks for everything after it. Both shapes have the same failure modes, just in different clothing. An offset calculation that uses the wrong base will skip a record or repeat one. A cursor that is built from the wrong field will jump or stall. A total count that disagrees with the actual pages will send a client asking for a page that can never arrive. Test data that only covers the middle of a list will never expose any of this.
How the tool works
You choose how many items the dataset should hold and how many items belong on each page, and the tool works out the pages for you. It tells you how many pages exist, which items fall on each page, and where a cursor would point after a given page. Everything runs in your browser, so the dataset is a planning and testing aid rather than a live server. You use it to know what correct output looks like, and then you compare your API's real output against it. That comparison is the whole point: a test dataset is only useful if it gives you an answer you can check independently.
The tool's arithmetic follows the standard convention. Page numbering starts at one, not zero, so page one holds the first items in the list. The number of pages is the total item count divided by the page size, rounded up, because a partial final page still counts as a page. A cursor after a page points at the first item of the next page, not the last item of the page you just saw. Those conventions sound obvious when stated, but a surprising number of pagination bugs come down to one side of an integration using a different convention from the other.
A worked example
Take 95 items with 10 items per page. Dividing 95 by 10 gives 9.5, which rounds up to 10 pages: nine full pages of 10 items and a final page of 5 items. Page 3 holds items 21 through 30, because pages 1 and 2 account for items 1 through 20, and page 3 starts at item 21. A cursor taken after page 3 starts at item 31, which is the first item of page 4. If your API instead returns item 30 again after that cursor, you have a repeat bug. If it returns item 32, you have a skipped record. Either way, the expected answer was known before you made the request.
A second example shows why the final page deserves attention. With 25 items and 10 per page, there are 3 pages, and page 2 holds items 11 through 20. Page 3 holds items 21 through 25, just five records. Page 4 should be empty or rejected, depending on your API's design, but it should never return items from page 3 again and never claim a total that implies more pages exist. Testing with 25 items is useful precisely because the final page is partial; a dataset whose total divides evenly by the page size never tests the partial-page path at all. When you design your own test cases, always include at least one total that leaves a remainder, one total that divides evenly, and one total smaller than a single page.
Common mistakes
The classic mistake is the off-by-one error in the offset calculation. Skipping page times size instead of (page minus one) times size moves every page one page too far, so page 1 returns what should be page 2, and the first records are never served at all. The mirror-image mistake is using a zero-based page number on one side and a one-based number on the other, which produces the same symptom. A second common mistake is trusting the total count without checking it. If the count says 95 but the pages only yield 90 items, five records are missing somewhere, and a client that loops until it has collected the total will loop forever or report an error it cannot explain.
Cursor mistakes are subtler. A cursor built from a timestamp can return duplicates when two records share the same timestamp, because "after this time" is ambiguous. A cursor built from a position that changes when records are inserted or deleted can skip records in a live dataset. A third mistake is testing only with small, tidy datasets. Ten items on pages of ten test exactly one page, which is the one case that cannot go wrong. Real bugs need totals that cross several boundaries, and they need a final page that is neither full nor empty.
Honest limitations
A test data builder is not a substitute for testing your real API. It tells you what correct pagination looks like for a given total and page size, but it cannot see your database, your filters, or your sorting rules. If your API filters records after paginating rather than before, the page sizes will be wrong in ways no dataset planner can predict. If your sort order is unstable, the same page can return different records on different requests, and no static dataset will catch that. The tool also works with simple sequential items; it does not model records with duplicate sort keys, changing data between requests, or access rules that hide some records from some callers. Those cases still need tests against the real system, with the builder's arithmetic as the expected answer.
Closing
Pagination is one of those features that looks finished the moment the first page loads, and that is exactly why it deserves boundary tests. Build a dataset with a partial final page, check page 3 against items 21 to 30, and confirm that a cursor after page 3 starts at item 31. If those three checks pass, most of the common bugs are already ruled out. For neighbouring work, JSON Studio helps you inspect real responses and JSONPath Tester helps you query them, while How to Format and Validate JSON covers keeping those responses readable and valid.