Start with a request map
When planning the budget for an offline-maps discussion feature within a hiking app, the first step is understanding that costs are tied to retrieval requests, not the volume of data returned. One successful search request costs one credit whether it returns three records,100 records or an empty list. Choosing a smaller page may help the reading experience, but it does not reduce that request’s credit price.
Draw the actions that actually reach the service. A first search, a requested next page, an explicit refresh and an item lookup can each be a separate retrieval. Scrolling through already loaded text is not a new request. One button press is not necessarily one credit if your backend fans it out into several calls.
Work through an assumed day
Here is a planning example, not observed traffic or a usage forecast: suppose the app completes 120 first-page requests,30 additional-page requests and 10 refreshes. That is 160 successful requests and 160 credits, equivalent to $0.16 at the stated rate. If 20 of those first-page responses are empty, the total stays 160 credits because those requests still succeeded.
Now suppose the interface automatically fetched three pages for every initial search even when nobody read them. That would be 360 requests before counting refreshes, rather than the 150 initial and deliberate next-page requests in the first example. The comparison is arithmetic under stated assumptions, not evidence about real users. Let your own measured request log replace the assumptions after implementation.
Separate the price from the purchase
The standard rate is $1 per 1,000 successful retrieval requests. The minimum paid top-up is $50 and provides 50,000 paid credits. There is no subscription, and paid credits do not expire. A hypothetical $0.16 day therefore describes consumption of a balance; it does not mean that a $0.16 top-up is available.
The optional 100-credit trial is conditional on network-wide anti-abuse eligibility and is separate from the paid conversion. Do not assume every signup receives it or present the feature as a free API. Create an invoice while signed in, then use its exact payable amount, recipient, token and network. Key and credits contains the account and payment steps.
Keep failures and uncertainty distinct
HTTP 400, 401, 402 and 429 are rejected before a retrieval credit reservation. They signal invalid input, a missing or invalid key, insufficient credits and rate limiting respectively. A failed upstream request releases its reserved credit, although reconciliation may remain pending. Do not describe all error paths as an immediate refund of a prior charge.
If the app loses the response after sending a request, it may not know whether the server completed a successful retrieval. A retry is another request, not a guaranteed free continuation. Record the uncertain outcome, preserve the query and avoid an automatic retry storm. The account view exposes successful, pending and refunded request counts for reconciliation.
Put a ceiling on the feature
Each query allows pages 1–100 and at most 100 records per request. Those are service bounds, not a recommendation to fetch every page. An app can choose a lower page budget for an interactive reading session and ask before further retrieval. Respect pagination.has_more and the final window boundary rather than searching for an empty page through repeated requests.
Do not count the potential 10,000-record window as guaranteed yield. A response can be empty, records can lack fields, and the archive does not promise full coverage. /v1/status is uncharged, but it neither returns the account balance nor probes search health. Local counters also need reconciliation; they cannot prove a lost request was free.
Review the choices the reader actually needs
For the proposed hiking panel, a short first page and a deliberate Show more action may be enough to compare discussion references. Save or reopen already stored app content without silently re-fetching it. If a reader explicitly asks to check an item again, explain that it is a fresh lookup and handle an unavailable result.
Use your own traffic evidence to decide whether limits or presentation need adjustment. Avoid turning the planning example into a promised cost per user, retention rate or performance benchmark. Return to /en/#field-notes for bounded pagination and local reading-list design.
