What are cursor-based and page-number pagination in APIs?

The two approaches describe where to continue in different ways.

With page-number pagination, a request identifies a numbered page—for example, “give me page 3, with 20 items per page.” The client uses the page parameter and any response metadata as the API documents them.

With cursor-based pagination, a request supplies a continuation value from an earlier response. It may be called a cursor or token, and it is not necessarily a human-readable page number.

These are general descriptions, not promises about parameter names, ordering, or response shape. The examples below illustrate possible formats; actual APIs can differ.

Yes. These invented examples illustrate the ideas only; they are not actual API formats.

A hypothetical numbered-page response might look like:

{
  "items": [{"id": "item-101"}],
  "page": 2,
  "pageSize": 20,
  "totalPages": 5
}

A hypothetical cursor response might look like:

{
  "items": [{"id": "item-101"}],
  "nextCursor": "example-token-abc"
}

Real APIs may use different names or provide a link instead. For example, Google Calendar documents a nextPageToken in a list response and says to pass it as pageToken on the next otherwise-identical request. Its maxResults sets a maximum; it does not guarantee that many results. [S1] Microsoft Data API builder documents $after as an opaque continuation token, $first as the maximum record count, and a response example with value and nextLink. [S2] These are specific examples, not universal field names or specifications for numbered-page pagination.

Check the documentation for the specific API endpoint and compare it with a sample response. Look for the documented request parameter, the response field or link used to continue, and the rule for using it. Don’t assume a token can be decoded, changed, or reused with different filters.

For Google Calendar, the documented next step is to pass nextPageToken as pageToken on an otherwise-identical request. [S1] Data API builder documents continuation using $after and a returned continuation value. [S2]

A practical sequence is:

1. Identify the documented page-size parameter, if there is one, and whether it is a maximum.
2. Find the response field or link that the API documents for continuing.
3. Use that value as instructed, keeping other request options consistent when required.
4. Stop when the documented response indicates there is no next batch.

Don’t infer that a missing total means the list is complete, or that an unfamiliar token is a page number. The cited examples don’t establish how other APIs behave.

Use this checklist for the specific API and endpoint you’re integrating:

1. Record the documented pagination request parameter or parameters and what each means.
2. Note the page-size limit and whether it is a maximum rather than a guaranteed result count.
3. Identify the exact response field or link used to continue.
4. Write down how the API signals the end of the result sequence.
5. Check whether filters and sort options must stay the same between requests.
6. Compare your client’s behavior with a small response example in that API’s documentation.

Keep a cursor as an opaque value unless the API documentation says otherwise. Keep page numbers and cursors distinct in your code and notes: they are different ways of expressing where to continue. Don’t hard-code one API’s field names as if they were standard.