hubspot api pagination failed on large contact export

TL;DR

Large exports fail when the pager mishandles the after cursor: reusing a stale cursor, changing sort mid-run, or requesting giant pages. Keep the sort stable, pass the returned after cursor verbatim into the next request, and persist the cursor so a crash resumes instead of restarting.

Error

(No error; the symptom is an export that stalls, repeats records, or dies partway with no clear failure.)

Steps

1. Set a stable sort (by id or created date) and a moderate page size (100). Expected: deterministic pages.
2. Loop: request a page, process it, take the paging.next.after value, and pass it as after on the next request. Expected: steady forward progress.
3. Persist the after cursor after each page (file or database). Expected: a crash resumes from the last cursor.
4. If records repeat or skip, check that nothing changed the sort or filters mid-run. Expected: a stable query produces no gaps.
5. For very large exports, prefer the exports API (async file) over manual paging. Expected: HubSpot builds the file server-side.

When to use

• Contact exports stall or loop on large lists.
• An agent pages the contacts endpoint and never finishes.
• After cursor errors or repeated pages.

When not to use

• Search API cursor resets (different endpoint behavior).
• 429s during paging (rate limits, different fix).

Tool compatibility

• HubSpot CRM API v3 list endpoints with cursor pagination.
• The async exports API for bulk extracts.

Variant phrasings

export stalls partway

Persist the cursor and resume; check sort stability.

paging returns the same page

Stale or mishandled after cursor.

Why it happens

Cursor pagination assumes a stable query. Agents that rebuild the request each iteration, or that lose the cursor on retry, break the chain and either loop or skip.

Edge cases

• Records created during the export can shift pages; export during quiet hours or accept the drift.
• The after cursor expires if unused for a long time; do not pause the loop for hours.
• Filtering on frequently-updated properties makes pages unstable; filter on stable fields.

Provenance

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

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

Thread query: hubspot api pagination failed on large contact export

TL;DR: Large exports fail when the pager mishandles the after cursor: reusing a stale cursor, changing sort mid-run, or requesting giant pages. Keep the sort stable, pass the returned after cursor verbatim into the next request, and persist the cursor so a crash resumes instead of restarting.