Should a paginated API return an exact total count?

Return an exact total count only when the client genuinely needs the exact number to decide what to do next. For routine list navigation, prefer an estimated or cached count, and omit counts entirely when nextPageToken is enough. Treat counting as separate work from fetching one page, and make the response say whether a count is exact or approximate.

Does every paginated API need a total count?

No. A paginated API needs a reliable way to continue or stop pagination first. Google AIP-158 says next_page_token is the way to communicate end of collection, and that responses may include total_size. It also says that total “may be an estimate” if the API documents that clearly.

That is the right default contract for many APIs. If the user is just moving through pages, an exact total often adds cost without changing behavior. Infinite scroll, event feeds, and admin tables with simple next/previous navigation usually work well with no total at all.

When is an exact count worth the cost?

Use an exact count when the exact number changes the user action now: exporting all rows under a hard cap, showing “select all 437 items,” or displaying a legally meaningful total.

The reason to be selective is that exact counting is its own operation. PostgreSQL aggregate documentation defines count(*) as “Computes the number of input rows.” That is straightforward, but it is still separate work from retrieving a single page. A page query can be cheap with a good access path while a full exact count remains expensive.

If you promise exact totals, do not hide that work inside normal page retrieval. Measure and budget count latency separately.

When should you return an estimate instead?

Return an estimate when users need scale, not precision: deciding whether to refine a search, understanding list size, or comparing “hundreds” versus “tens of thousands.”

PostgreSQL’s planner statistics are a useful model for this tradeoff. PostgreSQL planner statistics says reltuples values are “not updated on-the-fly” and “usually contain somewhat out-of-date values.” That is acceptable for estimates, as long as the API labels them honestly.

A practical response shape is:

{
  "items": [{"id": "p_101"}, {"id": "p_102"}],
  "nextPageToken": "page_2",
  "count": {
    "value": 12480,
    "accuracy": "estimated",
    "asOf": "2026-09-05T19:45:00Z"
  }
}

Prerequisite: your backend must be able to produce page tokens without waiting for recounts. If not, the count path and page path are still coupled too tightly.

What contract should you ship?

Use this checklist:

• Return exact when the workflow depends on the exact number now.
• Return estimated or cached when rough size is enough.
• Omit count when navigation only needs nextPageToken.
• Include metadata such as accuracy and asOf for any non-exact count.
• Offer an opt-in like includeTotal=exact|estimated|none if different clients have different needs.

One important limit: do not enforce business rules with a preflight count alone. If a write depends on “must remain under 10,000 items,” the enforced ordering boundary is the write path that accepts or rejects the change. A separate earlier GET can inform the UI, but it cannot guarantee correctness once concurrent writes exist.

Follow-up Q&A

Should only the first page include a count?
Yes, if that is documented. The count is often most useful when entering the list, not on every page fetch.

Should estimated totals be rounded?
Often yes. If the purpose is scale, returning 12500 with accuracy: estimated is clearer than implying false precision.

Next step: pick one high-traffic list endpoint, measure page latency and count latency independently, then update the API contract to make count accuracy explicit before promising exact totals.

Reviewed: 2026-09-05