LV2 · Toolooo Standard
API Pagination Planner
Compare pagination behavior and explore the tradeoff between page size and request count.
Navigation requirements & query assumptions
Compare the behavior
Cursor here means an opaque continuation-token API backed by keyset queries. Keyset is the query strategy; you can expose it through that same cursor API.
| Priority | Offset | Cursor API | Keyset query |
|---|---|---|---|
| Implementation | ✓ Simple limit + offset query | ~ Token encoding + keyset query | ~ Seek predicate + matching index |
| Deep pages | ! Skipped rows still require work | ✓ Seek after a boundary | ✓ Seek after a boundary |
| Changing data | ! Inserts/deletes before the offset shift results | ~ Avoids positional shifts; sort-key edits still matter | ~ Avoids positional shifts; sort-key edits still matter |
| Jump to page N | ✓ Direct offset from page size | ! Usually sequential token navigation | ! Needs a saved boundary or separate lookup |
| Deterministic ordering | ! Unique tie-breaker required | ! Backing query needs a unique tie-breaker | ! Unique composite seek boundary required |
| Previous page | ✓ Decrease the offset | ~ Reverse cursor/query or keep prior tokens | ~ Reverse comparator and sort direction |
At page 1,800 of this snapshot
Returning 50 records after 89,950 preceding records.
If 10% of requests reach this page and the rest fetch page 1, offset traverses about 9,045 rows per request on average. This two-point workload sketch makes deep-page frequency visible; measure the actual distribution.
Simplified row-work comparison, not a latency benchmark. Keyset bars exclude index-seek cost; joins, filters, sorting, cache state and index design can dominate. OFFSET still needs to compute skipped rows.
Smaller payloads or fewer requests?
40 KiB per full page
5,000 requests for a full scan
200 KiB per full page
1,000 requests for a full scan
1,000 KiB per full page
200 requests for a full scan
Full-scan record bytes remain about 195.3 MiB. More pages add request overhead; fewer, larger pages can increase latency and memory use.
Implementation checklist & assumptions
- Define sort columns and a unique tie-breaker. Index the actual filtering and ordering path.
- Decide whether results may change between requests. Keyset alone does not create a snapshot; edits to sort keys can repeat or omit records.
- For cursors, specify token validation, filter/sort binding, expiry and next/previous behavior. An opaque token is not authorization.
- Set a server-side page-size cap and measure representative shallow and deep requests.
- Define empty, last-page and concurrent-deletion behavior; decide whether exact total counts are worth their query cost.
Starting ranges are configurable-design heuristics: feed 20–50, admin 25–100, export 100–1,000; capped by this snapshot and a 256 KiB record-data budget. They are not service limits. If one record exceeds the budget, even a one-record page is too large; consider selecting fewer fields or separate detail requests.
Byte estimates assume equal records, no JSON envelope, no compression and full pages. Records and requests are bounded for responsive browser calculations. No database is queried.
References: PostgreSQL LIMIT/OFFSET · GraphQL pagination and opaque cursors.
Understand API Pagination Planner
What this tool helps you understand
Compare offset queries, cursor APIs, and keyset queries for your navigation and data-update pattern. Explore payload sizes, deep-page work, stable ordering, and page-jump requirements to choose an approach and a starting page-size range to test.
When to use it
Use API Pagination Planner when engineering, api, and backend work raises questions about API pagination planner, offset vs keyset, and cursor pagination and you need a concrete view before making the next move.
How to read the result
Use the calculated fit, spacing, timing, or risk as a planning baseline, then verify it against the physical, commercial, or technical constraints of the real project.
Assumptions and limits
Results are estimates based on the entered assumptions. Supplier specifications, team constraints, tolerances, and real-world conditions may require a different final plan.
Toolooo is part of Khizooology, created byKhizar Imtiaz (khizooo).