Implement cursor pagination
Page through changing social datasets without inventing numeric offsets.
Use the next_cursor returned by a list endpoint as an opaque value and send it back unchanged. Stop when it is absent, deduplicate by stable resource ID, and expect new or deleted remote content to change later pages.
What this means in practice
Use the next_cursor returned by a list endpoint as an opaque value and send it back unchanged. Stop when it is absent, deduplicate by stable resource ID, and expect new or deleted remote content to change later pages.
Use the documented brand and account boundaries consistently across the scheduler, REST API, SDK, MCP tools, SSE consumers, and webhooks. That makes the same social operation explainable to an operator and reproducible by an integration.
Implementation checklist
Store the cursor only for the exact endpoint, brand, filters, and sort context that created it.
Treat cursors as opaque and URL-encode them when used in a query string.
Merge pages by resource ID instead of array position.
Handle an expired or invalid cursor by restarting the listing safely.
Use sync timestamps or event IDs for durable incremental workflows where documented.
Operational details
Cursor pagination is more stable than numeric offset when provider data changes between requests.
Different endpoint families can have different cursor lifetimes.
A cursor is not an authorization token and does not replace brand checks.
Common mistakes to avoid
- Do not decode a cursor and depend on its internal representation.
- Do not reuse a cursor after changing filters or brand selection.
- Do not assume page size equals the requested limit when provider data is filtered.