Paginate API results and inspect coverage

Recognize the three response parts

Read data, meta and pagination together. Data contains the returned rows or object. Meta supplies request ID, as-of time, source, delay, session and coverage information. Pagination describes the current page and any continuation. A successful HTTP request does not establish that all market observations were available or returned. Missing fields stay null rather than being converted to zero, and unknown trade classification remains unknown. Treat completeness as an explicit property of the response selection, not an assumption inferred from the number of rows visible in one client view.

Follow the cursor until it ends

For cursor-paginated routes, continue using pagination.next_cursor_id or the provided next_url while the response indicates more work. Preserve the route and original selection. The public cursor is an opaque continuation bound to its account, route and parameter selection; it is not an upstream URL that should be edited or decoded by your client. A changed symbol, session, time range or filter needs a new first request. A cursor that has expired cannot establish a continuation merely because its text still looks like a valid token.

Handle short and empty filtered pages

Filtered tape scans can reach their per-request work budget before finding many matching rows. Such a response can be short or empty and still provide a next cursor. Stopping whenever count is smaller than limit would omit later matches. Inspect scan_complete and scanned-through coverage as well as the cursor. Continue while the contract supplies a continuation, then record the resulting coverage. A filter that finds no trades in one scanned region is not evidence that the entire requested session had no qualifying activity.

1. Request the first page with a fixed instrument, session, range and filters.
2. Save its rows and coverage, then follow the provided continuation.
3. Stop when the continuation ends, not merely when an intermediate page is short.

Keep time and native ordering precise

Public API timestamps use UTC Unix milliseconds, while some native ordering values such as nanosecond keys are strings to preserve integers beyond JavaScript's exact numeric range. Keep those strings intact when storing or comparing the documented native order. Start bounds are inclusive and end bounds are exclusive, which makes adjacent ranges easier to partition without double-counting the shared boundary. Use the exchange-local trading date where a date parameter is required. An overnight session can belong to the next trading date rather than the local calendar date at its start.

Treat changing rankings differently from tapes

Some ranked views use offset pagination and can report snapshot_changed as the underlying snapshot refreshes. Rows can move between pages, producing repeats or omissions if you interpret several changing pages as one immutable ranking. Respect that warning and restart when your analysis requires a fresh coherent selection. Cursor-based tape ordering and snapshot ranking are different contracts. Late corrections or repaired history can also justify re-reading a session rather than assuming a previously downloaded file remains the final account of all eligible observations.

Inspect partial, delayed and withheld coverage

Coverage can describe missing ranges, capture start, truncation, unavailable inputs, plan-withheld data or an incomplete scan. Delayed flags and delay values separately describe timeliness. For example, an otherwise valid delayed stock response is not made real-time by repeatedly polling it. A retained range can be partial because capture began late, while a plan boundary can deliberately limit the available window. Keep these explanations with your saved rows so downstream totals do not imply a full-session observation that the response explicitly did not provide.

Recover and report a failed continuation

On an invalid or expired cursor, start a new scan with the intended selection rather than modifying the token. On a retryable service or rate response, honor Retry-After and keep retry work bounded. All keys share 250 requests per rolling minute and a 30-per-second burst limit, with no credits. For support, provide the first request's safe selection, request IDs near the failure, pagination and coverage fields, and whether the query changed between pages. Keep the developer key private and do not substitute an incomplete scan's row count for a verified market total.