agent confused the two cursors in the response - it used ending_before as the next-page cursor and walked backwards...

TL;DR

Responses with two cursors have a forward one and a backward one - using the wrong one pages in the wrong direction. Read the provider's docs to name which cursor advances the list, wire only that cursor into the next-page parameter, and verify after the first two pages that items are actually progressing forward. A direction check on page two catches the mixup before it walks the whole list backwards.

The query

agent confused the two cursors in the response  -  it used ending_before as the next-page cursor and walked backwards forever

Steps

1. Name both cursors from the provider's docs

Find the response fields (commonly starting_after / ending_before or next / previous) and write down which one advances toward newer items and which one goes back. Do not infer from the names alone - confirm with the docs' pagination section.

Expected: a written mapping: forward cursor field, backward cursor field.

2. Check which cursor the generated code uses

Read the pagination loop and see which response field feeds the next request's cursor parameter. If it is the backward field, that is the bug - every page steps backwards.

Expected: the exact field name the code currently uses, matched against the step-1 mapping.

3. Wire the forward cursor into the next-page parameter

Change the loop to send the forward cursor (the one that advances the list) as the next request's cursor. Ignore the backward cursor entirely unless the client genuinely needs to page backwards.

Expected: the next-page parameter receives only the forward cursor field.

4. Verify direction on the first two pages

Fetch page one and page two, then compare a stable ordering field (ID, timestamp) across the boundary. Items on page two must continue the order from page one, not repeat or reverse it. Automate this as an assertion.

Expected: a passing direction assertion on real data.

5. Guard against cursor cycling

Add the standard backstops: a seen-cursor set and a maximum page count. Walking backwards forever and walking forwards forever look identical in the logs without them.

Expected: the loop terminates even if a cursor is ever wired wrong again.

Use this when

• Pagination returns items in reverse or repeats the same items walking backwards
• The response contains two cursor fields and the code uses one of them
• Page two's items precede page one's items in the list order
• The loop runs far longer than the list warrants without 400s or 429s

Not for this skill when

• The API has a single cursor (then there is nothing to confuse)
• The sort order itself is descending by design (check the sort parameter first)
• Cursors are expired or malformed (different error signature)
• Items repeat going forward (dedupe or stability problem)

Variant phrasings

pagination walked backwards through the list

Same fix. Step 4's direction assertion is the fastest confirmation.

used the previous-page cursor for the next page

Exactly this bug under a different description. Steps 2 and 3 swap the field.

Why it happens

Two similarly named cursor fields invite a coin flip, and the agent flipped wrong. Nothing in the generated code looks broken - the loop is well-formed, the cursor is passed through correctly, the requests succeed. The failure is purely directional: every request is valid, it just asks for the previous page instead of the next one. Because no error ever fires, the loop runs until a backstop (which was never generated) stops it.

Edge cases

• Provider's forward/backward naming is inverted from the convention: trust the docs' pagination section over the field names. Step 1 exists for this.
• Client genuinely needs bidirectional paging: keep both cursors, but name the variables forward_cursor and backward_cursor explicitly so the next reader cannot mix them.
• Sort parameter interacts with cursor direction: changing the sort order can flip which cursor is "forward." Pin the sort order in the client and document the pairing.
• First page has no backward cursor: handle the absent field without crashing, and do not treat its absence as a signal about direction.

Provenance

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