Exchange API pagination: prove which history you retrieved

Exchange API pagination retrieves history in limited pages, so a successful response does not prove that an account's history is complete. Define the account, product, instruments and time range first; follow the endpoint's documented cursor or time-window rules; deduplicate by scoped event identity; and preserve evidence that every required window was traversed. Mark unavailable or unresolved periods explicitly rather than treating them as zero activity.

A missing fill can distort inventory, fees and a strategy journal. A repeated fill can do the same in the opposite direction. The useful question is therefore not “Did the download finish?” but “Which history does this record actually cover?”

Write the history contract before requesting pages

Give a history import a precise scope: venue, account or subaccount, production or test environment, product category, instrument set, event type and requested interval with timezone. A spot fill query does not establish a futures funding ledger. A current open-order list cannot establish all completed executions.

Also distinguish three limits: records per page, maximum time span per request and how far back the endpoint retains accessible records. Increasing the page limit does not extend a retention boundary. Splitting a year into smaller windows does not establish that the year is available.

Record the endpoint documentation and review date alongside the import. If required history predates its supported range, investigate an official export or other supported record source and label any remaining gap. Do not silently move the requested start forward until the API responds.

Cursor names are instructions, not ordinary English

Coinbase Exchange illustrates a direction trap. Its array endpoints such as fills and orders return recent items by default. To move toward older results, its pagination guide specifies the response's CB-AFTER value in the next request's after parameter. Its before direction retrieves newer pages. Those words describe the result set, not the chronological meaning a reader might guess. Coinbase Exchange pagination rules.

Bybit's V5 execution endpoint instead returns nextPageCursor for the next page. It accepts a maximum seven-day span between start and end, defaults to seven days when neither is provided, and allows up to 100 records per page. A seven-day response with 100 executions can still require more pages inside that same interval. Bybit V5 execution-history parameters.

Binance Spot's account trade list requires a symbol and supports an inclusive fromId: returned trade IDs are greater than or equal to that value. Its time-bounded queries have a 24-hour maximum span, and the supported parameter combinations do not combine fromId with start and end times. An importer must choose a supported traversal method rather than mixing useful-looking parameters. Binance Spot account trade list.

These are endpoint examples, reviewed on 23 October 2026. They do not establish KLINEO support for a particular history-import method. Check current product and endpoint rules before implementing one.

Freeze the target and prove progress

For a backfill, choose a fixed upper boundary instead of repeatedly asking for “now.” Otherwise new activity can continually expand the job. A fixed time filter still does not create a snapshot guarantee: late publication or corrections can change what a later request returns.

Within each supported window, carry forward the documented continuation value. Keep filters consistent across that cursor chain. Save the returned page, relevant pagination headers, observation time and continuation checkpoint together, committing the checkpoint only after the page is durably recorded. A restart can then repeat a page without losing its events. If the same identity returns conflicting quantities or fees, preserve both observations for investigation instead of silently adding them or overwriting the discrepancy.

Track whether the cursor or documented boundary advances. A repeated cursor, incompatible response or page budget exhaustion should halt the job with an unresolved status. It should not create a “complete” badge. A short page is a completion signal only when the endpoint contract makes it one; follow the documented terminal condition.

Schedule this work within the exchange API request budget. A rate-limit response is an interrupted traversal, not an empty historical interval.

A worked ledger: nine rows, seven fills

The following is a hypothetical import for one spot account, one BTC market and a fixed past interval. All fills are buys; fees are excluded. This fictional source permits overlapping retrieval, and a deliberate overlap or retry repeats boundary events. The page layout is a teaching fixture, not a reproduction of any venue's responses.

The repeated F103 and F105 contribute 0.001 + 0.002 = 0.003 BTC to the raw-row excess. Counting all rows overstates gross acquired quantity by that amount. Recording each scoped fill once produces 0.021 BTC.

The deduplication key needs context. Use the provider-defined execution identity with the account, product and instrument scope required to avoid collisions. An order ID is insufficient when an order has several fills. A timestamp is insufficient when several executions share a timestamp. Do not invent a missing fill merely because numeric IDs have a gap; the API must define any sequence-continuity guarantee.

Store identifiers without lossy conversion and calculate quantities from exact decimal representations. The API decimal precision guide explains why a reliable identity ledger can still produce the wrong totals if its numbers are rounded during parsing.

Overlap helps only when identity is reliable

Suppose a timestamp-only page ends with F102, while F103 has exactly the same timestamp. Advancing the next start to the last timestamp plus one millisecond can skip F103. Repeating the timestamp can return duplicates, or even the same full page forever if no additional tie-breaker is available.

Prefer the endpoint's documented ID or cursor traversal. If a supported time-window method is necessary, account for its inclusive or exclusive boundaries and timestamp precision. Deliberately overlapping adjacent requests can help catch boundary records, but deduplication must then be explicit. If all records at one timestamp exceed a page and the API offers no way past the tie, flag that boundary as unresolved; overlap alone cannot prove completeness.

Bybit specifically warns that executions with equal execTime can have sorting issues and provides a suggested ordering combination. That warning is another reason to keep execution identity separate from timestamp order. Bybit execution ordering caveat.

Keep a coverage receipt beside the fills

A reusable receipt should answer these questions:

Keep a completed-through boundary separate from the latest event timestamp. An interval with no activity can be fully traversed; a recent fill does not prove all earlier windows were covered. A successful empty response is evidence about that query's scope and visibility, not automatic proof of no account activity.

A private-stream session expiry can trigger this kind of catch-up even when the public market feed keeps moving. Reconcile the overlapping stream and REST records by execution identity, and verify the subscription separately. The broader WebSocket recovery guide covers continuity after reconnecting.

When the purpose is resolving an uncertain submission, pagination is one part of the order reconciliation process. Retain the original order identity, cumulative fills and unresolved gaps. A tidy import cannot substitute for evidence that the relevant order and all of its executions were found.

Editorial method: Prepared with AI assistance from official exchange documentation reviewed on 23 October 2026. The three-page ledger and coverage receipt are original hypothetical teaching examples; no live account import, exchange export comparison or KLINEO recovery test was performed.