What is API pagination and why does it prevent huge responses?

Published on 2026-10-20 by frfrand

Paginación de APIs con limit/offset y cursores: cómo devolver listas grandes, manejar cambios de datos y evitar errores de rendimiento.

Pagination allows returning a list of data in parts instead of sending all records at once. It is common in catalogs, order histories, and APIs with thousands or millions of items.

If a store has two million products, downloading the entire database every time someone opens the catalog does not seem like a great idea.

The comparison with a library

Imagine you ask for programming books. The librarian does not empty all the shelves onto the table. She shows you a selection and lets you move on to the following results.

A paginated API does something similar: it receives information about how much to return and from what point to continue.

Pagination by limit and offset

An API could offer:

GET /api/productos?limit=20&offset=40

That requests up to twenty products starting from a certain position. It is simple to implement and allows building traditional pages: first, second, third.

But it has limits. With many rows, some queries with a high offset can be costly. And if products are added or removed between requests, the user could see repeated records or skip others.

That is why you should not assume that "page 4" permanently identifies the same set of data.

Cursor pagination

Another technique uses a cursor that represents a logical continuation position. The response can include a list and a value such as next_cursor.

The client sends that cursor to retrieve the next batch, without necessarily having to count from the beginning every time.

This approach may work better for lists that change frequently, but the cursor must be designed with a stable order and appropriate attributes. It is not a magic key that solves any consistency problem.

What should a good API return?

In addition to the items, it can include a continuation indicator and links or parameters to request the next set. Sometimes it is useful to report the total number of records, but calculating it can also have costs.

What matters is clearly documenting the rules: maximum page limit, applied order, admitted filters, and behavior if the cursor expires or is invalid.

The client should not be able to arbitrarily request twenty million records if that operation can affect all other users.

Order is essential

Imagine querying the twenty newest orders first. If you do not explicitly define how to order them, the database engine does not promise to always return a logical sequence. Pagination without a stable order can produce confusing results.

It is useful to sort by a date and resolve ties with a unique identifier. The exact strategy depends on the engine and how records are inserted.

And how does it compare with a search?

Searching and paginating are distinct problems. A search decides which records match the filters; pagination decides how many are delivered and how to continue.

If the user changes the filters, they should normally restart the traversal. Reusing the previous cursor with another query can produce incorrect results.

Three errors that appear in production

Allowing huge limits: a single request can consume too much memory or processing time.

Omitting ordering: pages lose consistent meaning.

Inventing an exact total without measuring: in large databases, calculating the exact number can be more expensive than returning the requested page.

For sensitive APIs, authorization must also be verified: pagination must not allow obtaining other people's records.

Where does ArduMaker come in?

If you publish a backend on an ArduMaker VPS, pagination helps reduce the load of its queries and the volume of data transferred. The panel can facilitate deployment, but the API behavior and its database correspond to the project.

In summary: paginating is not dividing a visual screen into pages. It is designing how to retrieve large data sets efficiently, predictably, and securely.

Sources: Microsoft API design guide · LIMIT and OFFSET in PostgreSQL.