Make the next action small
Suppose the illustrative hiking app asks for offline maps in hiking with limit=3 and page=1. A reader opens the returned references and decides whether another group would help. Show more should request the next page for that same question. It should not quietly start a crawl of every page or change the query while keeping the old results on screen.
The visual cue for the user is a Show more control that appears when the response permits another page. Disable repeated activation while that action is pending, and keep already displayed references available. Each successful page request consumes one credit, including an empty page. A reader who stops before requesting another page avoids that future request; leaving the screen does not guarantee cancellation or refund of a request already sent.
Keep the request state together
Keep q, subreddit, other chosen filters and limit unchanged as page increments. If the reader changes the phrase or date range, start a new result sequence at page 1. Mixing a second page from a different question into the old list makes the reading history misleading, even when both requests succeed.
The archive uses _doc order. It is not chronological, relevance or score order; min_score is a filter rather than a sorting instruction. You can reorder the records already fetched for presentation, but that does not identify the globally newest or best matches. No stable-snapshot guarantee accompanies repeated page requests.
Use the response, not an empty-page guessing loop
pagination.has_more is based on a lookahead record where the request window allows one. Offer the next action only when has_more is true and the page is below 100. Do not keep fetching until an empty page appears: the service already exposes a continuation signal, and extra successful requests cost credits.
Read pagination.total with pagination.relation. eq means an exact count under that response’s counting semantics; gte is a lower bound, not a statistical estimate; unknown supplies no reliable total and may accompany null. In a hypothetical first response exposing three records with total 4 and relation gte, the copy could say that at least four matches are indicated. It must not say there are exactly four.
Recognize the capped window
The limits are 100 records per request and 100 pages. On page 100 at limit 100, a full final page has no room for an extra lookahead record. pagination.window_exhausted can therefore be true while has_more is false and relation is gte. False has_more at this boundary is not proof that the archive contains no further matches.
An empty page beyond page 1 also cannot establish a global total; the gateway marks the total unknown for that case. Describe the actual boundary to the reader, such as Reached this search window, rather than All discussions loaded. Narrowing a query can organize further work but does not turn bounded requests into an exhaustive export.
Merge carefully and keep failures recoverable
If an actual record identifier is present, your app can use it to avoid displaying the same record twice in its own accumulated list. Choose identity rules from the fields you actually receive; do not invent an ID for a missing one or merge different records solely because their text looks alike. Local deduplication does not prove the remaining list is complete.
A failed next-page request should leave the earlier records and query intact, with an explicit retry choice. Keep the pending page number separate until you know the outcome, and handle an out-of-order response in your own application logic. The API does not provide a cursor endpoint or manage this UI state for you. Return to /en/#field-notes for examples of separate loading states and request budgeting.
