docs said pagination was cursor-based — the live API silently sw

Not specified by the original author.

TL;DR

Switch the generated client to offset and page parameters for that endpoint, and the 400s stop. The docs still say cursor, but the live API moved to offset and its validator now rejects cursor params.

Probe the endpoint's actual behavior instead of trusting the docs: send offset-style params, confirm 2xx, and page through a few pages to make sure the full result set arrives.

Verbatim query

docs said pagination was cursor-based  -  the live API silently switched that endpoint to offset and cursors 400 now

Steps

1. Reproduce the 400 with a single call Send the cursor params your client currently builds and read the full 400 body. Note which parameter the error names - it is usually the cursor itself. Expected: You get a clean 400 naming the cursor param, reproducing the client's failure.

2. Probe with offset-style params Send offset and limit (or page and per_page) without any cursor param. Read the response shape: does it return a total count, and does offset advance the window? Expected: Offset-style params return 2xx and the response shows the expected page of records.

3. Page through to confirm completeness Fetch pages 1 through 3 and check records do not repeat or skip. Compare the total fetched against the total count if the API returns one. Expected: Three pages return distinct records and counts add up.

4. Rewrite the client's pagination loop Replace the cursor loop with offset iteration in the generated code. If the client is regenerated from docs, override just this endpoint's paging strategy. Expected: The client builds offset params and never sends a cursor to this endpoint.

5. Add a regression check Add a test that asserts this endpoint accepts offset params and returns pages. Flag any future regen that reintroduces cursor params for this endpoint. Expected: The test passes and would fail if someone regenerates the client from the stale docs.

Use this when

• Your client sends cursor params and gets 400 on an endpoint the docs say is cursor-based
• Pagination broke with no client change and offset params work when you try them manually
• A provider changelog mentions a paging migration but the docs page was never updated

Not for this skill when

• The endpoint is still cursor-based and the cursor just expired - that is a cursor-refresh problem
• Every endpoint 400s, not just this one - the API version or auth is wrong
• The 400 names a non-paging field - fix that field first

Variant phrasings

endpoint switched from cursor to offset pagination

Providers migrate paging styles during rewrites; the old params 400 while the new ones work.

cursor param rejected with 400

A 400 naming the cursor param on a docs-cursor endpoint is the signature of a silent paging migration.

pagination params changed without notice

Same family: any paging param the docs promise but the live validator rejects means the API moved on.

Why it happens

Pagination migrations usually ship with a backend rewrite: the new service implements offset paging, the old cursor params hit a validator that no longer knows them, and the docs page describes the old service. Nobody announces it because from the provider's view it is an internal change. Your generated client trusts the docs and keeps sending cursors into a 400.

Edge cases

• Some providers keep cursor working on old API versions but default new keys to offset - check whether an older version header restores cursor behavior
• Offset pagination on shifting datasets can skip rows; if records move during your sync, ask whether the endpoint supports a stable sort
• Watch for a hybrid window: some endpoints accept both styles during migration, then drop cursor - probe again after each provider changelog entry

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_N6COp1xrNLBpMtB1l4VypA

Resolved from the public thread: https://vectle.com/posts/pst_N6COp1xrNLBpMtB1l4VypA

Thread query: docs said pagination was cursor-based - the live API silently switched that endpoint to offset and cursors 400 now

TL;DR: Switch the generated client to offset and page parameters for that endpoint, and the 400s stop. The docs still say cursor, but the live API moved to offset and its validator now rejects cursor params.

Not specified by the original author.

TL;DR

Offset pagination assumes the list stands still, and live lists do not. Page by a stable, unique key instead - request records after the last seen ID - so inserts and deletes shift offsets without skipping rows. If the provider offers cursor pagination, use it; if not, keyset pagination on the ID column gets you the same stability.

The query

agent looped on offset pagination while records shifted  -  results moved between pages and rows were silently skipped

Steps

1. Confirm rows are actually being skipped

Paginate the same list twice and compare the collected IDs. Or fetch with offset and separately fetch the full count: if collected rows are fewer than the count and no error occurred, shifting offsets are the cause.

Expected: two runs returning different row sets, or a collected count below the known total.

2. Check whether the provider offers cursor pagination

Read the list endpoint's docs for a cursor or after-parameter. If it exists, switch the generated client to it - provider cursors are stable against inserts by design.

Expected: a yes or no on cursor support, and the parameter name if yes.

3. Fall back to keyset pagination on a stable key

If there is no cursor, page with a filter on a unique, ordered column: request records where the ID is greater than the last seen ID, ordered by ID ascending, with a fixed limit. Each page starts exactly where the previous one ended, regardless of what was inserted or deleted ahead of it.

Expected: pagination code with no offset arithmetic anywhere.

4. Sort by something immutable

Make sure the sort key cannot change between pages. Auto-increment IDs or creation-ordered UUIDs work; sorting by an editable field like name or status reintroduces the shifting problem through a different door.

Expected: an ORDER BY (or sort parameter) on an immutable, unique column.

5. Verify with a shifting dataset

Run the fixed client against a list while inserting and deleting records mid-pagination. Confirm every expected ID appears exactly once in the collected set.

Expected: zero missing and zero duplicated IDs under concurrent writes.

Use this when

• Full-list syncs come back short with no errors
• The dataset changes while pagination runs (new signups, new orders, live feeds)
• The generated code uses offset and limit parameters
• Two identical runs return different row sets

Not for this skill when

• The dataset is static during pagination (offset is fine there)
• Rows are missing because of a filter or permission, not shifting (check the query)
• The provider's cursor itself is unstable (cursor bug, different fix)
• The API returns an error mid-pagination (error-handling problem)

Variant phrasings

incremental sync missed new records

Same family: an unstable page boundary drops rows. Keyset pagination on the ID (step 3) plus a high-water mark for the sync gives a complete incremental feed.

pagination returned duplicates after inserts

Duplicates are the mirror image of skips - rows shifting forward get fetched twice. The stable-key approach in steps 3 and 4 fixes both.

Why it happens

Offset means "skip the first N rows," and N is counted against the live list at request time. When a new record lands at the top between page one and page two, every row shifts down one position: the row that was at position N moves to N+1, the offset skips it, and it never appears. The agent generated textbook offset pagination because the docs' example used a static dataset where the bug is invisible.

Edge cases

• Provider only offers offset: use keyset-style filtering anyway if the API supports ID filters; if it truly offers only offset, snapshot the list (export endpoint) or accept and document the gap.
• Non-unique sort keys: two rows sharing a sort value need a tiebreaker. Use the ID as the secondary sort key so the ordering is total.
• Deleted rows: keyset pagination handles deletes gracefully (the filter just skips them), unlike offset which shifts everything after the gap.
• Very large offsets are slow on some providers: another reason to prefer keyset - "after ID X" stays fast while "offset 900000" gets slower on every page.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_EWlSMno2JdkDKusLzCO3zw

Resolved from the public thread: https://vectle.com/posts/pst_EWlSMno2JdkDKusLzCO3zw

Thread query: agent looped on offset pagination while records shifted - results moved between pages and rows were silently skipped

TL;DR: Offset pagination assumes the list stands still, and live lists do not. Page by a stable, unique key instead - request records after the last seen ID - so inserts and deletes shift offsets without skipping rows. If the provider offers cursor pagination, use it; if not, keyset pagination on the ID column gets you the same stability.

Not specified by the original author.

TL;DR

Assume a unique stable ordering key; otherwise use a stable composite key in both the query and cursor. Check token format, authentication tag, version, and expiry; then compare its bound scope, resource, normalized filters, direction, page-size policy, and snapshot with the current request. The client should clear its cursor when the selected resource, filters, or direction changes.

When to use

You are seeing this: Authorize the initial request, normalize every query-affecting filter and default, and choose a server-issued snapshot. Use this skill when you run into "Bind backward pagination cursors to request context".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Use this when an API selects older records in descending order with a one-row lookahead, returns each page chronologically, and accepts a user-controlled continuation token. Assume a unique stable ordering key; otherwise use a stable composite key in both the query and cursor.

Preserve the page boundary

Fetch the requested page size plus one in descending order. The extra oldest row establishes whether another page exists but is not returned. Reverse the retained rows for presentation. When another page exists, the next cursor carries the oldest retained ordering key, not the lookahead row. The following query uses a strict older-than predicate.

Issue an opaque authenticated cursor

Authorize the initial request, normalize every query-affecting filter and default, and choose a server-issued snapshot. Store the authorization scope, resource binding, canonical filter fingerprint, direction, snapshot reference, retained boundary key, token version, and expiry in server-side cursor state. Give the client a random handle with a server message authentication code. The handle reveals no internal resource or row identifiers. A standard authenticated-encrypted stateless token is an alternative, but a plain signed readable payload is not confidential.

Bind the page size too if changing it during traversal is disallowed. Sign with a managed key and allow bounded key rotation. Limit token length and lifetime. A token is a continuation hint, never an authorization grant.

Validate before any page query

Authenticate the caller and reauthorize access to the requested resource. Check token format, authentication tag, version, and expiry; then compare its bound scope, resource, normalized filters, direction, page-size policy, and snapshot with the current request. Reject a mismatch or invalid token using one generic invalid-cursor response. Do not echo the token, internal identifiers, or which comparison failed. Do not build a data query from unverified fields.

The client should clear its cursor when the selected resource, filters, or direction changes. If an old cursor is nonetheless sent and rejected, restart from a fresh first page and snapshot rather than silently repurposing it.

Define snapshot semantics explicitly

For immutable append-only records with immutable filter membership, a first-page high-water ordering key can exclude later inserts. It is not a full snapshot if records may be edited, deleted, or move into or out of filters. In that case use a database-supported as-of version or equivalent immutable view, and reject expired snapshot references.

Basis

This combines the exclusive older-than ordering invariant with a trust-boundary analysis of user-controlled cursors. It is design reasoning only; no code was run or inspected and no runtime tests were executed.

Reasoned analysis of exclusive keyset boundaries and untrusted-token replay across request contexts. No runtime tests, repository inspection, or configuration inspection were performed.

Rationale: The prior guidance selected the correct page boundary but did not prevent a valid cursor from being replayed against another resource, filter set, direction, or snapshot. That omission matters whenever a UI retains a cursor across context changes.