agent assumed the list endpoint sorted by created_at - the API sorts by updated_at and the incremental sync missed...

TL;DR

Sync on the sort key the API actually uses (updatedat here), not the one you assumed. Records that get edited after creation move position under updatedat ordering, so a created_at watermark skips them. Change the watermark, backfill the gap, done.

agent assumed the list endpoint sorted by created_at  -  the API sorts by updated_at and the incremental sync missed new records

Steps

1. Verify the real sort. Page the list endpoint and compare the order of returned records against their created and updated timestamps. Expected: you can state the actual sort key and direction with evidence.
2. Change the sync to filter and watermark on updated_at (or whatever the API sorts by). Expected: the query parameter and the stored cursor both use the real key.
3. Backfill the gap: run one historical sync covering the period the broken sync ran, and reconcile against your store. Expected: the previously missed records appear and counts match.
4. Handle updates as upserts, not inserts, since updated_at ordering means you will legitimately re-see edited records. Expected: reprocessing an edited record does not create a duplicate.
5. Watch one full sync cycle and diff the synced set against a full list pull. Expected: zero missing and zero duplicated records.

Use this when

• An incremental sync misses records that were created earlier but edited later.
• The API docs are vague about sort order and the agent picked created_at by convention.
• Record counts in your store drift below the provider's counts over time.

Not for this skill when

• Records are missing because pagination broke - see the pagination skills.
• The API genuinely sorts by created_at - then the bug is elsewhere.
• You need deleted records too - that needs a separate tombstone or audit endpoint.

Variant phrasings

• incremental sync missed records because API sorts by updatedat not createdat
• sync watermark on created time skipped updated records
• list endpoint ordering assumption broke incremental sync

Why it happens

createdat ordering is the intuitive default, so agents reach for it without checking. But providers sort by updatedat because their own UIs want "recently active" first. Any record edited after creation then sorts ahead of newer-but-untouched records, and a created_at watermark walks right past it.

Edge cases

• updatedat and createdat can be identical for never-edited records, which hides the bug in small test datasets.
• Some APIs let you pick the sort via a parameter; if so, request the key your sync is built for explicitly.
• Ties on identical timestamps need a secondary stable key (id) or records can be skipped at page boundaries.

Provenance

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