API pagination divides a large collection into smaller responses and gives clients a way to retrieve the next portion. For a new collection endpoint, define pagination from the start: choose a page-size default and maximum, specify exactly how clients continue and detect the final page, and decide whether users need to jump to arbitrary positions or simply traverse results. Offset, cursor, and link-based pagination each suit different needs; none is universally best.
What API pagination does—and why to design it early
Instead of returning every item in one response, a paginated endpoint returns a bounded set and continuation information. Clients make additional requests until the service signals that no more results remain. This limits the amount of data transferred per request and gives clients a predictable traversal mechanism.
Pagination affects an endpoint’s contract, not just response size. Google’s AIP-158 says collection-returning RPCs should provide pagination at the outset because adding it to an existing method can be behaviorally incompatible, even when the new fields are technically additive. A client that previously treated one response as the whole collection may otherwise silently miss records.
Before implementing a collection endpoint, write down its ordering, filters, page-size behavior, continuation mechanism, and terminal-page signal. The client must know whether it can jump to a position, how to carry its query forward, and what definitively means “done.”
Recommended Free Tools
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Choose a pagination pattern
| Pattern | How it advances | Good fit | Trade-offs to consider |
|---|---|---|---|
| Offset or skip | A numeric position tells the service how many records to skip, often paired with a limit. | Clients need familiar positional access or the ability to jump to a position. | Consider how deep positions are handled by your storage and how inserts or deletions can shift a changing result set. These concerns depend on the implementation; the cited guidance does not establish a universal performance result. |
| Cursor or keyset | A continuation token or resource key identifies where the next request should resume. | Clients primarily traverse results in sequence and the service can provide continuation state. | Define stable ordering and preserve the original query. Clients generally cannot assume random access to numbered pages. Tokens must remain opaque if the API design requires it. |
| Response links | The response supplies a link—commonly in a response header—to the next page or other pagination targets. | The server should direct clients to the correct endpoint-specific continuation URL. | Clients must read and follow the response links rather than construct undocumented parameters themselves. |
Offset or skip
Offset-style requests express a position, for example, “skip 100 and return the next 25.” Google AIP-158 defines a skip approach, while Zalando’s REST guidance recommends preferring cursor pagination over offset pagination. That recommendation is not proof that offset is always wrong or that cursors are always faster: performance depends on the data store, query, ordering, and workload.
Offset is useful when positional navigation is important, but think through what “position 100” means while the collection changes. If records are inserted or removed before that position between requests, later pages may shift. Document the expected behavior rather than implying a snapshot if the service does not provide one.
Cursor or keyset
A cursor continues a traversal from a service-defined point. It can be an opaque page token or, as in Stripe list methods, an object ID used with starting_after or ending_before. Cursor pagination suits sequential retrieval when the client does not need to jump directly to page number 40.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
For a robust cursor contract, define the ordering that makes “next” meaningful, bind continuation to the relevant query context, and tell clients to reuse the server-provided value. Do not make clients decode or manufacture internal cursor state.
Link-based pagination
GitHub’s REST API uses Link response headers to direct clients to additional pages. This makes the server’s continuation instructions explicit: read the header, select the appropriate relation such as the next link, and request that URL. The precise link relations and availability depend on the endpoint and response.
Define page size and completion behavior
Set a default and a maximum
Document a default page size and an upper bound. Under Google AIP-158, page size should not be mandatory: a missing or zero value selects the documented default; a request above the maximum is reduced to the maximum; and a negative value is rejected. An API may return fewer records than requested, so clients must not treat a short page alone as proof that the collection has ended.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Use an unambiguous terminal signal
Tell clients exactly what ends traversal. In AIP-158, an empty next_page_token indicates the end of the collection. For SCIM cursor pagination, RFC 9865 says the nextCursor field is omitted only when no result pages remain. These are distinct conventions; follow the contract of the API you are using.
Keep continuation separate from authorization
A continuation token tells the service where to resume; it is not a credential and must not replace ordinary authorization checks. AIP-158 also requires API page tokens to be opaque, URL-safe strings that users cannot parse. If internally stored tokens expire, that is an API-specific lifecycle rule: AIP-158 offers three days as a rule of thumb, not a universal token lifetime.
How to retrieve every page reliably
- Make the initial request. Include the endpoint’s documented filters, sort order, and optional page size. Do not assume parameter names are shared across APIs.
- Process the returned items. Store or consume each page before continuing, especially for large collections.
- Read the continuation supplied by the API. Use the next token, cursor, or response link exactly as documented; do not infer hidden cursor contents or construct a continuation URL from undocumented rules.
- Preserve the query context. Carry forward filters, sort order, and other original inputs. RFC 9865 requires subsequent SCIM cursor requests to preserve the original query parameters other than the cursor itself.
- Stop only on the defined terminal signal. Check the empty token, omitted cursor, absent next link, or other documented convention. A page shorter than requested is not a reliable generic stopping rule.
- Handle failures without losing your place. Retain the last successful continuation value and apply the API’s documented retry and token-expiry behavior. Do not assume a cursor remains valid indefinitely.
Illustrative client loop
The following pseudocode illustrates an opaque-token contract in which an empty next_page_token ends traversal. Adapt field names, authentication, error handling, and request construction to the API’s actual documentation.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
token = null
while true:
response = get_collection(page_token=token, page_size=100)
process(response.items)
token = response.next_page_token
if token is empty:
breakThis loop is not suitable unchanged for every API. A link-based API requires following its response link, while Stripe’s list methods use object-ID cursors and Stripe client libraries provide auto-pagination helpers. GitHub clients should parse the response’s Link header. Use the vendor’s documented convention rather than translating all APIs into one assumed parameter format.
How common API conventions differ
| API convention | Continuation | What the client should do |
|---|---|---|
| Google AIP-158 design guidance | page_token and next_page_token |
Pass the returned token to continue; an empty next token signals the final page. Page tokens are opaque and do not grant authorization. |
| GitHub REST | Link response header |
Read and follow the relevant server-provided link to retrieve additional pages. |
| Stripe list methods | starting_after or ending_before, with object IDs |
Use the list method’s documented direction and cursor; Stripe client libraries include auto-pagination helpers. |
| SCIM cursor pagination (RFC 9865) | cursor request parameter and nextCursor response field |
Keep the original query parameters other than the cursor unchanged; an omitted nextCursor means no more result pages. |
Stripe’s documentation has described a default list-method limit of 10; its search API reference has described a limit from 1 through 100 with a default of 10. Those are Stripe-specific documented values, not general API defaults, and the pagination reference is subject to change; check the current Stripe pagination documentation for the method you use.
Pagination for APIs is not pagination for search engines
API pagination is a request-and-response contract for clients. Search-engine pagination concerns how crawlers discover and index web pages. Google Search Central says crawlers generally find pages through URLs in anchor href attributes and generally do not click buttons or trigger user actions that load more content. For crawlable web content, use sequential links between paginated pages and handle their URLs correctly; an API’s next_page_token alone does not provide that navigation to a crawler. See Google’s pagination and incremental page-loading guidance.
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Common pagination problems and fixes
- The client stops after a short page. A service can return fewer items than requested without reaching the end. Continue until the documented terminal signal appears.
- The client repeats or skips records. Check that it uses the returned continuation state, preserves the original filters and sort order, and follows the API’s ordering contract. With offset pagination, changes to the collection can shift positions.
- A client gets an invalid token or cursor. Confirm that it sent the exact server-provided value to the correct endpoint and preserved required query parameters. If the API documents token expiry, restart or recover according to that API’s rules.
- Page-size requests behave unexpectedly. Check the documented rules for omitted, zero, negative, and over-maximum values. A service following AIP-158 uses its default for missing or zero size, clamps excessive values to the maximum, and rejects negative values.
- A request does not include all expected records. Verify that the client followed every next token or link and stopped only at the defined terminal condition. Also check whether filters or permissions exclude records; pagination does not override either.
- Deep offset requests are slow. Measure the actual endpoint and query plan under representative data and load. Cursor pagination may be a better design for sequential traversal, but no universal speed advantage is established for every backend.
- A token is mistakenly treated as access authorization. Enforce the normal authorization checks on each request; continuation state only identifies where to resume.
Or skip the browser setup
Pagination is for API collections; if your task is to capture web pages as screenshots or PDFs, ScreenshotNeo provides a one-call screenshot API and an MCP server for AI agents. For example, cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for options and response details. Cookie banners, newsletter popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for free.
Frequently Asked Questions
Can an API return fewer items than the requested page size and still have another page?
Yes. A short page does not by itself establish that the collection has ended; use the API’s documented continuation signal.
Does a page token authorize access to the next page?
No. A page token is continuation state, not a substitute for the API’s normal authorization checks.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Is cursor pagination always faster than offset pagination?
No universal performance result follows from the cited guidance. The outcome depends on the backend, query, ordering, and workload.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
