Guides

Pagination

Endpoints that can return a lot use cursors. You ask for a page; if there is more, the response tells you where the next page starts.

Cursors#

Make the request without a cursor.
Read meta.nextCursor. If it is null or missing, that was the last page.
Otherwise make the same request again with cursor set to that value.

meta on a page with more after it

{
  "apiVersion": 1,
  "migrationPhase": 3,
  "sourceOfTruth": "per_account",
  "nextCursor": "MTc5MDcyNTI1MzE1MnxyYXRfMDFNM0VaUkJBVzYyMVFWTjczQkhLRU5QOEI"
}

Cursors are opaque. Different endpoints encode them differently, so never build or edit one; pass back exactly what you were given, with the same other parameters.

Paginated endpoints#

Endpoint	Default	Maximum
Community feed `/v1/feed/for-you`	20	40
A user’s ratings `/v1/users/{userId}/ratings`	30	100
A user’s reviews `/v1/users/{userId}/reviews`	30	100
A user’s lists `/v1/users/{userId}/lists`	30	100

Page size#

limit sets how many items you get. A value above the maximum is capped at the maximum. Anything that is not a positive whole number (0, -5, abc) is ignored and you get the default. Endpoints without a cursor still accept limit:

Endpoint	Default	Maximum
Rankd Charts `/v1/charts`	20	50
Search the catalogue `/v1/music/search`	10	25
Reviews of an album, song or artist `/v1/music/{type}/{id}/reviews`	20	50
Search people `/v1/search/people`	25	50
Search lists `/v1/search/lists`	25	50

Ordering#

Ratings are ordered by when they were last changed, reviews by when they were written, and lists by when they were last updated, newest first. Something changed while you are paging can move to the front, so a long walk through a busy profile can miss or repeat an item. When that matters, dedupe on id.