Move list endpoints from offset to cursor pagination

trailhead-api · Claude · branch feat/pagination · claude-opus-5 · cwd /home/user/code/trailhead-api · id c10daf7d-dc65-2ac0-af13-e1cf3304d642 · 2026-06-07 13:26 · 2 msgs · 16 tools · 1 min read · updated 3 months ago

Offset paging skipped rows when records were inserted mid-scan; cursors fixed it.

tools: Read, Edit, Bash
← trailhead-api Download .md
cd /home/user/code/trailhead-api && claude --resume c10daf7d-dc65-2ac0-af13-e1cf3304d642Resume may fail — session is older than Claude Code's ~30-day transcript retention window.
Tool calls
Edit Edit: 7 calls (50.0%) 7 Read Read: 4 calls (28.6%) 4 Bash Bash: 3 calls (21.4%) 3
Token usage7.0K total
Input5.9K
Cache creation0
Cache read0
Output1.2K
Cache hit ratio0%· cold cache

Offset paging skipped rows when records were inserted mid-scan; cursors fixed it.

Conversation

Turn 1 — User

Clients paging through the list endpoint are missing records.

Turn 2 — Assistant

Classic offset problem — a row inserted before the current offset shifts everything and the next page skips one. I moved to cursor paging keyed on a stable sort column plus the primary key as a tiebreak.

The cursor is opaque to clients and encodes both values, so ordering stays stable even when rows are inserted mid-scan.

Turn 3 — User

Is the old parameter still accepted?

Turn 4 — Assistant

Yes, for now — it still works and returns a deprecation header. Removing it is a breaking change and belongs in a version bump.

Subjects

  • [[REST API]]
  • [[SQLite]]
  • [[Python]]

Keyboard shortcuts

⌘K / Ctrl+KOpen command palette
/Focus search
g hGo to home
g pGo to projects
g sGo to sessions
j / kNext / prev row (tables)
?Show this help
EscClose dialogs

Structured queries

Mix key:value filters with free text in the palette:

type:sessionOnly session pages
project:llm-wikiFilter by project name (substring)
model:claudeFilter by model name (substring)
date:>2026-03-01Sessions after a date
date:<2026-04-01Sessions before a date
tags:rustPages mentioning a tag/topic
sort:dateSort results by date (newest first)

Example: type:session project:llm-wiki date:>2026-04 sort:date