Guides

Pagination

List endpoints return one page at a time. Follow next_cursor until it is null.

Cursors

next_cursor
Each page carries the cursor for the next one, or null on the last page. Pass it back as cursor.
Bound to the query
A cursor belongs to the filters and sort that produced it. Change any of them and start again at page one; replaying a cursor under different filters answers 400 cursor-invalid (CURSOR_INVALID), never a wrong page.
Opaque
Treat a cursor as an opaque string: store it, pass it back unchanged, never build or edit one.
No expiry
A cursor from your own key does not expire. With the public demo key a cursor lasts an hour, after which paging starts again at page one.
Starting again
Any 400 cursor-invalid means start again at page one: a cursor issued before a change to the cursor format is refused the same way. Paging reaches at most the first 100,000 results.

Page sizes

limit sets the page size. Out of range is 400 validation-failed.

/v1/search1-50, default 20
/v1/discover1-50, default 20
/v1/recommendations1-50, default 10
/v1/titles/{titleRef}/episodes1-50, default 20
/v1/titles/{titleRef}/credits1-50, default 20
/v1/people/{personRef}/filmography1-50, default 20
/v1/changes1-500, default 100
/v1/changelog1-50, default 20
/v1/account/requests1-200, default 50

Reading every page

// Reads every page of a search. The cursor is passed back unchanged with the same filters.
const base = "https://api.wambesha.com/v1/search?q=gladiator&limit=50";
const headers = { Authorization: `Bearer ${process.env.WAMBESHA_API_KEY}` };
const titles = [];
for (let cursor = null; ; ) {
  const url = cursor ? `${base}&cursor=${encodeURIComponent(cursor)}` : base;
  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`${res.status} ${(await res.json()).code}`);
  const page = await res.json();
  titles.push(...page.titles.items);
  cursor = page.titles.next_cursor;
  if (cursor === null) break;
}