Pagination

Every list endpoint returns a page:

{
  "data": [ … ],
  "next_cursor": "eyJmIjoi…",
  "has_more": true
}

• limit sets the page size: 50 by default, 200 at most. A larger value is lowered to 200.
• When has_more is true, pass next_cursor back as cursor to get the next page. On the last page, next_cursor is null.
• The next page’s address is also in the Link header, for clients that follow links: Link: <https://getrefract.app/v1/library?cursor=…>; rel="next".

Cursors are opaque and bound to the query

Pass a cursor back exactly as it came, with the same filters. A cursor that was edited, or sent with other filters or to another endpoint, answers 400 with INVALID_CURSOR: start again from the first page.

The order of each list

Lists follow a stable order, so walking every page visits each item once.

Endpoint	Order
/v1/library, /v1/watchlist	Stable, by Refract id. Not chronological.
/v1/history/episodes	By show, then season, then episode.
/v1/history/movies	Stable, by play id. Sort by watched_at on your side for a timeline.
/v1/ratings, /v1/lists	Stable, by id.
/v1/lists/{id}/items	The list’s own order (position), then id.

A title added while you page may or may not appear in the pages you have left. To keep a copy in step with a member’s account, a feed of changes arrives in a later release.