Cursor pagination

Cursor pagination

Cursor pagination 是一種分頁策略，使用一個不透明的記號（稱為「游標」）來標示結果集中的位置，而不是依賴像 page=2 或 offset=100 之類的數字偏移量。用戶端將游標傳回伺服器（例如透過 after_cursor 參數）以請求下一頁。伺服器在回應中會返回下一頁的新游標。

In context

Polymarket 的 Gamma /markets 端點需要基於游標的分頁：呼叫必須使用先前請求返回的 after_cursor 值，而不是 offset 參數。這種鍵集（keyset）式的方法在大型或頻繁更新的結果集中改善了效能與一致性，因為伺服器可以從一個穩定的位置繼續，而不必每頁都從頭掃描。Gamma 在每個分頁回應中返回 next_cursor；請將該值作為 after_cursor 來獲取後續頁面。

Practical notes

• Opaque token: 將游標視為不可檢視的字串。不要在客戶端嘗試解析或自行構造它。
• No numeric offset: Gamma API 會拒絕數字偏移；在 /markets 的分頁請使用 after_cursor。該端點支援與 after_cursor 一起使用的 limit（最大 1000）。
• Ordering matters: 游標分頁與查詢的排序相關聯。如果您更改排序欄位，可能無法使用先前的游標繼續掃描。
• Robust clients: 如果您打算恢復長時間的掃描，請保存游標，並處理先前發出的游標變得過時或不返回結果的情況。

See also

• /glossary/gamma-api