On this page
Define the export unit and snapshot boundary
The source dates shown in this guide identify documentation checks on 22 October 2026, not original publication dates. Follow each citation for the pagination conventions being discussed. Before requesting a page, write the export contract: endpoint or controlled source reference, resource type, stable identity field, requested ordering, filter, page size, cursor policy, terminal condition, and snapshot or cutoff evidence if the API supplies one.
This is different from a database watermark review. A cursor is a navigation value supplied by an API contract; it may encode position, a snapshot, or another server-defined state. Do not infer that a cursor is a timestamp, a durable checkpoint, or a guarantee that records cannot change while the export runs.
| Contract item | Record before the first page | Question |
|---|---|---|
| Resource | Type, endpoint reference, filter | What exactly is one export unit? |
| Identity | Stable id field or explicit unknown | How will duplicates and gaps be compared? |
| Order | Requested and observed order fields | Can pages be reconciled in one order? |
| Cursor | Initial value and encoding policy | What value starts and advances the chain? |
| Snapshot | Server or client boundary if present | Can the source change during export? |
| Terminal rule | Missing, null, or exhausted next link | What evidence ends the chain? |
Record the exact self link or equivalent request identity for every page. JSON:API says a self link should contain query parameters needed to identify the resource, including pagination parameters when applicable JSON:API, (opens in a new tab). A request log with only a page ordinal cannot reproduce a cursor export.
Capture links and cursor transitions as evidence
If the endpoint follows JSON:API, inspect the links object for first, last, prev, and next. A link can be absent or null when a relationship is unavailable. If the API uses HTTP Link fields, record the relation type and target according to RFC Editor, (opens in a new tab). Do not assume that a next link proves the next response will be stable, unique, or complete.
- Store the page request identity, response identity, retrieval result, and source reference.
- Extract the next relation or cursor without normalizing away its opaque value in the evidence ledger.
- Compare the next value with earlier values and flag repeats or cycles.
- Check that the next request uses the same resource, filter, ordering, and snapshot contract.
- Record an explicit terminal observation only when the API contract defines it or the owner approves the rule.
Synthetic page chain
{
"pages": [
{"request": "cursor=start", "self": "cursor=start", "next": "cursor=B", "ids": ["synthetic-001", "synthetic-002"]},
{"request": "cursor=B", "self": "cursor=B", "next": "cursor=C", "ids": ["synthetic-003", "synthetic-004"]},
{"request": "cursor=C", "self": "cursor=C", "next": null, "ids": ["synthetic-005"]}
],
"ordering": "synthetic_id_ascending",
"snapshot": "synthetic-boundary-A"
}The page chain is invented. The cursor values are opaque labels, not timestamps or real API tokens. Keep the source response separate from this worksheet, and redact any cursor that could carry private query state before sharing a report.
Reconcile records, order, and terminal evidence
Use the stable identity field to compare adjacent pages and the full chain. Count duplicates, identify gaps only when the ordering contract permits that conclusion, and retain page-local positions for every finding. An empty page is not automatically terminal when a next relation remains. A repeated cursor is not automatically a duplicate record, but it is a chain issue that needs a bounded stop policy.
| Observation | Safe interpretation | Next action |
|---|---|---|
| Next is absent or null under the contract | Possible terminal page | Retain the response and terminal rule |
| Next repeats an earlier cursor | Potential cycle | Stop under the policy and hold completeness |
| Page ids overlap | Duplicate observation across pages | Preserve page positions and investigate ordering |
| Expected order jumps | Possible gap or changed source | Compare source contract and snapshot evidence |
| Empty page has next | No records in this page, chain continues | Follow the next relation under limits |
| Filter or order changes | Pages are not one export chain | Split exports and reconcile separately |
| Response fails or times out | Chain has an unobserved segment | Mark incomplete; do not fill silently |
| All pages reconcile to terminal evidence | Selected chain is internally consistent | Report scope and remaining unknowns |
Do not infer missing records from a count unless the endpoint contract supplies a trusted total and snapshot. A total can be stale, approximate, filtered, or unavailable. Report “no gap observed under this order and identity rule” instead of “complete” when the source provides no terminal or snapshot evidence.
Use a fixture and a page reconciliation worksheet
Test the method with synthetic pages containing contiguous ids, a duplicate across adjacent pages, a repeated cursor, an empty page with a next link, a changed filter, and a response with no terminal relation. Keep response bodies small and identifiers invented. The fixture is for the review method, not evidence about a production API.
| Ledger field | Synthetic value | Review question |
|---|---|---|
| Page ordinal | Local sequence number | Was every response retained in order? |
| Request identity | Path, filter, order, cursor class | Is it the same export chain? |
| Self identity | Response self link or equivalent | Can this page be reproduced? |
| Next relation | Opaque cursor or null | Did the chain advance or terminate? |
| Record ids | Stable synthetic ids | Are duplicates or permitted gaps visible? |
| Snapshot | Boundary label or unavailable | Can source changes be distinguished? |
| Disposition | Complete, incomplete, cycle, or hold | What evidence supports the state? |
Keep export reconciliation separate from downstream decisions
Pagination evidence can show how a selected chain advanced and where it stopped. It cannot establish ownership, permission to retain or share records, privacy clearance, semantic accuracy, or commercial demand. Keep those decisions in separate provenance, privacy, rights, and owner-approved records.
Pair this guide with the data provenance log for endpoint and snapshot notes and export guidance for producer-specific behavior. After the owner has a supported non-health scope, authority to describe the collection, and a controlled page ledger or synthetic fixture, the qualified appraisal request path may be a next preparation step. It does not call an API, certify completeness, create a quote, match a buyer, issue a legal opinion, or grant a license.
Takeaways
- Define resource, identity, order, cursor, snapshot, and terminal rules before paging.
- Retain self and next links or equivalent request identities for every page.
- Reconcile duplicates, gaps, repeated cursors, empty pages, filter changes, and failures separately.
- Use synthetic fixtures and stable identifiers before exposing response bodies.
- Scope any completeness statement to the observed chain and its evidence boundary.