---
title: "API Pagination: Offset vs Cursor vs Keyset Compared"
description: "API pagination splits a long list into pages. Compare offset, page number, cursor and keyset pagination with real Stripe, GitHub and Shopify shapes."
canonical: https://luckpanda.app/blog/api-pagination-offset-vs-cursor
author: "Dhrumil Barot"
author_bio: "Dhrumil is a small-business operations and compliance expert. Dhrumil built LuckPanda so small businesses can run invoicing, inventory, accounts and compliance in one place."
published: 2026-11-15
updated: 2026-11-15
category: "AI agents and automation"
keywords: "api pagination"
language: en
---

# API Pagination: Offset vs Cursor vs Keyset Compared

API pagination returns a long list in pages. Compare offset, page number, cursor and keyset pagination with real Stripe, GitHub, Shopify and LuckPanda shapes.

By [Dhrumil Barot](https://luckpanda.app/about#founder), Founder. Published 15 Nov 2026. Updated 15 Nov 2026. 7 min read.

**TL;DR:** API pagination returns a long list in pages instead of all at once. Use cursor (or keyset) pagination for any list that changes while people read it or grows past a few thousand rows; use offset or page numbers only for small, stable lists where users need to jump to page 7. LuckPanda's REST API, like Stripe and Shopify, uses cursors: you pass limit and the next_cursor from the last answer until it comes back null.

[Read the LuckPanda API and MCP docs](https://luckpanda.app/modules/workspace/developers) to see a cursor-paged API built for invoices, payments and ledgers.

API pagination is the contract between a server and a client for reading a list in slices: the client asks for a page size and a position, and the server returns the items plus a way to ask for the next slice. There are four common ways to state the position: an offset (skip 200 rows), a page number (page 5 of 20 per page), an opaque cursor (a token the server hands back) and a keyset (the last ID or timestamp you saw). Offset and page number are easy to build and let users jump around, but they get slower with depth and can skip or repeat rows when data changes. Cursor and keyset stay fast at any depth and stay correct under inserts, at the cost of no random jumps and usually no total count.

## Offset vs page vs cursor vs keyset: the comparison table

| Criteria | Offset | Page number | Cursor (opaque token) | Keyset (seek) |
| --- | --- | --- | --- | --- |
| Request shape | limit=20&offset=200 | page=11&per_page=20 | limit=20&cursor=eyJpZCI6... | limit=20&after_id=9001 |
| Response tells you | items, maybe total | items, maybe total and last page | items, next cursor or has_more | items, last key in the page |
| Speed on page 5,000 | slow: the database still reads and skips every earlier row | slow, same as offset | constant | constant, with an index on the key |
| New rows while reading | items shift, so you skip or repeat some | same as offset | stable | stable |
| Jump to page N | yes | yes | no | no |
| Total count | cheap on small tables only | same | usually not returned | usually not returned |
| Who uses it | many internal admin APIs | GitHub (many endpoints) | Stripe, Shopify, LuckPanda | under the hood of most cursor APIs |

Cursor and keyset are close relatives. A keyset request exposes the sort key (after_id=9001). A cursor wraps that key, plus the sort order and filters, in an opaque string so the server can change how it pages without breaking clients.

![Offset reads and skips earlier rows, while a cursor seeks straight to the next row](https://cdn.sanity.io/images/pcmcvz9y/production/c578209b24a61608bc286f1ff733dd51764a6a31-1344x326.png?w=1200&auto=format&fit=max)

*Offset cost grows with depth; a cursor seek stays about the same.*

## What is the difference between cursor and offset pagination?

Offset pagination says "skip N rows, then give me M". The server runs something like ORDER BY created_at LIMIT 20 OFFSET 200. Two problems follow. First, the database cannot jump to row 200: it reads and throws away the first 200 rows, so page 5,000 at 20 per page means reading about 100,000 rows to return 20. Second, the position is a count, not a place. If three invoices are created while a client is on page 1, every row moves down three places and page 2 repeats three rows it already showed. If rows are deleted, it skips some instead.

Cursor pagination says "give me M rows after this exact item". The server turns the cursor into a condition such as WHERE (created_at, id) < (the last values you saw), ordered and limited the same way. With an index on those columns the database seeks straight to the right place, so page 5,000 costs about the same as page 1, and inserts before your position cannot shift what comes next.

![New rows shift offset pages but not cursor pages](https://cdn.sanity.io/images/pcmcvz9y/production/157cf63017cde664f1ac125097fe4b8f9ad9ff36-1344x410.png?w=1200&auto=format&fit=max)

*Two inserts push 104 and 103 onto offset page 2 again; the cursor starts after 103.*

## How the big APIs do it: Stripe, GitHub and Shopify

These are the shapes you will meet in practice, read from each provider's docs on 2026-11-15.

| Criteria | LuckPanda REST API | Stripe | GitHub REST | Shopify Admin |
| --- | --- | --- | --- | --- |
| Style | cursor | cursor (object ID) | page number or cursor, via Link header | cursor (GraphQL connections; REST page_info is legacy) |
| Request params | limit, cursor | limit, starting_after, ending_before | per_page, page (or before/after, since) | first/after, last/before |
| Next page signal | next_cursor (null on the last page) | has_more plus last object ID | Link header rel="next" | pageInfo.hasNextPage and endCursor |
| Default page size | 25 | 10 | 30 on the issues example | 50 on REST; set first on GraphQL |
| Maximum page size | 50 (500 on the change feed) | 100 | 100 on most endpoints | 250 |
| Over the maximum | rejected by the schema | 1 to 100 only | silently reduced to the maximum | 250 cap; bulk operations beyond that |

### Stripe: object IDs as cursors

Stripe's list methods (customers, charges, invoices) accept limit, starting_after and ending_before. limit runs from 1 to 100 with a default of 10. starting_after takes the ID of the last object you received, so the cursor is simply an object ID, and the two direction parameters are mutually exclusive. Each answer is a list object with data, has_more and url; keep calling with the last ID while has_more is true. Stripe's search methods page differently: you pass page with the next_page value from the previous answer, and total_count is only accurate up to 10,000 ([Stripe pagination docs](https://docs.stripe.com/api/pagination), [Stripe search pagination](https://docs.stripe.com/api/pagination/search)).

### GitHub: the Link header

GitHub's REST API returns a link response header with URLs for rel="next", "prev", "first" and "last", following the Web Linking standard ([RFC 8288](https://www.rfc-editor.org/rfc/rfc8288)). Endpoints page with page, before/after or since, and GitHub tells you to follow the URLs rather than build them. per_page is capped at 100 on most endpoints, and a bigger value is quietly reduced to the maximum, so a request for 500 succeeds with 100 rows and no error. rel="last" is left out when GitHub cannot calculate it ([GitHub docs: using pagination](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api)).

### Shopify: connections and PageInfo

Shopify's GraphQL Admin API returns lists as connections. You ask for first: 50 (or last), and each connection returns pageInfo with hasNextPage, hasPreviousPage, startCursor and endCursor; pass endCursor as after for the next page. One page holds at most 250 items, and Shopify points large exports to bulk operations. The REST Admin API is legacy since 1 October 2024; it pages with a Link header carrying page_info, which must be used exactly as given, with limit defaulting to 50 and capped at 250 ([Shopify GraphQL pagination](https://shopify.dev/docs/api/usage/pagination-graphql), [Shopify REST pagination](https://shopify.dev/docs/api/usage/pagination-rest)).

## How LuckPanda pages invoices, payments and the ledger

LuckPanda is a business operating system for small businesses, and every action in it is one command used by the app, the REST API and the MCP server alike, with the same permission checks. Its list endpoints are cursor-paged, which matters for business records: invoices get issued and payments recorded while an integration is reading, and an offset would skip or repeat them. From the published [OpenAPI file](https://luckpanda.app/openapi.yaml):

- List endpoints such as documents and proposals take limit (1 to 50, default 25) and cursor (a string of up to 500 characters).
- Every page has the same shape: data, an array of records, and next_cursor, which is a string while there is more and null on the last page. Your loop is: call, read data, stop when next_cursor is null, otherwise call again with it.
- The change feed returns every change in the business in sequence order, with limit up to 500, has_more, latest_sequence and a next_cursor that is always returned, so a sync job can store it and ask later for only what happened since.
- Ledger lines are cursor-paged, never truncated, with totals, so a report export does not silently stop at a row cap.
- Money is integer minor units in the document's currency (4900 USD = 49.00) and the API is versioned by date with the LuckPanda-Version header, so a paging loop written today keeps working.

API and MCP access come with the account; paid actions such as issuing and sending are charged per module ($4.99 a month, ₹199 for a business in India). Agents can search, read and draft, but issuing, sending, payment links and recording payments are refused for agent keys. LuckPanda does not offer offset or page-number paging on these endpoints, so a "page 7 of 40" screen needs to be built on your side from cached pages.

## Which pagination is best for large datasets?

Cursor or keyset pagination is best for large datasets. Their cost per page stays flat however deep you go, because the database seeks with an index instead of counting past earlier rows, and new rows do not shift pages under a reader. For full exports beyond what paging handles comfortably, use the provider's bulk or export route (Shopify bulk operations) or a change feed such as LuckPanda's /changes, and keep the cursor between runs.

Choose by the job:

- **Choose cursor pagination if** the list changes while people read it (orders, invoices, events, feeds), you sync data between systems, or the list can reach tens of thousands of rows. This is the default for public APIs.
- **Choose keyset if** you control the database and the sort is a single unique, indexed column such as id or (created_at, id). It is a cursor without the encoding.
- **Choose offset or page numbers if** the list is small and stable (a settings list, a few hundred products), users need to jump to a page, and you need a total count.
- **Avoid** offset for infinite scroll, data syncs and anything sorted by a column that is not unique: ties make rows appear on two pages.

## How do you return the next page link?

There are two common ways to tell the client where the next page is. Pick one and use it on every list endpoint.

1. **In the body.** Return next_cursor (LuckPanda), has_more with the last ID (Stripe) or pageInfo.endCursor (Shopify GraphQL). This is easy to read in any client and survives proxies that strip headers.
2. **In a Link header.** Return link: \<https://api.example.com/items?cursor=abc>; rel="next" as defined by RFC 8288 (GitHub, Shopify REST). This keeps the body a plain array and lets clients follow URLs without knowing your parameter names.

Whichever you choose, treat cursors as opaque (clients must not decode or build them), keep the sort order and filters inside the cursor, return null or omit the link on the last page, and document the default and maximum page size.

## API pagination best practices

- Sort by a unique, stable key. created_at alone has ties; use (created_at, id).
- Set a default and a maximum page size and document both; say whether over-max values are rejected or reduced (GitHub reduces them silently).
- Make cursors opaque and short-lived enough that you can change their format.
- Do not promise an exact total on large lists; Stripe caps total_count accuracy at 10,000 for search.
- Keep filters stable across pages: a cursor from one filter must not be reused with another.
- Give clients a way to resume: a change feed or a cursor they can store, so a failed sync restarts where it stopped instead of from page 1.

For related reading, see how [LuckPanda for AI agents](https://luckpanda.app/agents) exposes the same commands over MCP, what to record in [MCP server logging](https://luckpanda.app/blog/mcp-server-logging), and the rest of the [Workspace module](https://luckpanda.app/modules/workspace).

## Questions

### What is API pagination?

API pagination is a way for an API to return a long list in smaller pages. The client asks for a page size and a position (an offset, a page number or a cursor), and the response includes the items plus what to send to get the next page.

### What is the difference between cursor and offset pagination?

Offset pagination skips a number of rows, so it gets slower on deep pages and can repeat or skip rows when data changes. Cursor pagination starts after a specific item, so it stays fast and stable, but you cannot jump straight to page N.

### Which pagination is best for large datasets?

Cursor or keyset pagination. The cost of each page stays about the same at any depth when the sort column is indexed, and inserts do not shift pages. For full exports, use a bulk export or a change feed.

### How do you return the next page link?

Either put a next cursor in the response body, as LuckPanda (next_cursor), Stripe (has_more and the last ID) and Shopify GraphQL (endCursor) do, or send a Link header with rel="next" as GitHub does under RFC 8288. Return nothing for next on the last page.

### What page size should an API use?

Pick a default between 10 and 50 and a maximum around 100 to 250. Stripe uses 10 and 100, GitHub 30 and 100 on most endpoints, Shopify 50 and 250, and LuckPanda 25 and 50.

### Does cursor pagination support a total count?

Usually not, because counting a large filtered list costs as much as reading it. Some APIs add an optional count: Stripe search returns total_count only on request and accurate up to 10,000.

[Start free with LuckPanda](https://luckpanda.app/signin), create an API key in Settings and page through your documents with limit and next_cursor. See [pricing](https://luckpanda.app/pricing) for what is free and what is paid per module.

## More guides

- [Webhook Examples: Real Payloads, Headers and Signatures](https://luckpanda.app/blog/webhook-examples)
- [MCP Server Logging: Where Logs Go, What Changed and What to Record](https://luckpanda.app/blog/mcp-server-logging)
- [MCP vs API: What Changes When an AI Agent Is the Caller](https://luckpanda.app/blog/mcp-vs-api)

## Related tools

- [Invoice generator](https://luckpanda.app/tools/invoice-generator): Bill a client in any currency, with tax worked out as you type.

## About the author

**Written by [Dhrumil Barot](https://luckpanda.app/about#founder)**, Founder. Dhrumil is a small-business operations and compliance expert. Dhrumil built LuckPanda so small businesses can run invoicing, inventory, accounts and compliance in one place. [LinkedIn](https://www.linkedin.com/in/bdhrumil) · [X](https://x.com/fyidhrumil)
