Users

A user’s lists

GET/v1/users/{userId}/lists

No API keyRate-limitedPaginated

Their public lists, most recently updated first.

Parameters#

Path parameters#

Name	Type	Description
userIdrequired	string	A Rankd user id: `usr_` then 26 characters. Get one from Look up a user by username. Pattern: `^usr_[0-9A-Z]{26}$` · Example: `usr_01KY0JGXMWTT8H9WFN9RTM5JP9`

Query parameters#

Name	Type	Description
limit	integer default 30	How many items to return. Default 30, at most 100. Larger values are capped at 100; anything that is not a positive whole number gives the default.
cursor	string	The `meta.nextCursor` of the previous page. Leave it out for the first page. Cursors are opaque: pass them back unchanged.

Try it#

Sends a real request to the production API through this site. No credentials are used, so you see exactly what anyone would.

Request#

curl "https://api.rankdmusic.app/v1/users/usr_01KY0JGXMWTT8H9WFN9RTM5JP9/lists"

const response = await fetch('https://api.rankdmusic.app/v1/users/usr_01KY0JGXMWTT8H9WFN9RTM5JP9/lists');
const body = await response.json();

if (!response.ok) {
  const code = typeof body.error === 'string' ? body.error : body.error.code;
  throw new Error(`Rankd API ${response.status}: ${code}`);
}

const { data, meta } = body;
// meta.nextCursor: pass it as ?cursor= for the next page

import Foundation

let url = URL(string: "https://api.rankdmusic.app/v1/users/usr_01KY0JGXMWTT8H9WFN9RTM5JP9/lists")!
let (data, response) = try await URLSession.shared.data(from: url)

guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
    throw URLError(.badServerResponse)
}

let body = try JSONSerialization.jsonObject(with: data) as? [String: Any]
let result = body?["data"]
let nextCursor = (body?["meta"] as? [String: Any])?["nextCursor"] as? String

import requests

response = requests.get("https://api.rankdmusic.app/v1/users/usr_01KY0JGXMWTT8H9WFN9RTM5JP9/lists", timeout=10)
body = response.json()

if not response.ok:
    error = body["error"]
    raise RuntimeError(error if isinstance(error, str) else error["code"])

data = body["data"]
next_cursor = body["meta"].get("nextCursor")

Response#

A successful response is { "data": …, "meta": … }. data is an array of ListSummary objects, and meta is a PageMeta.

Field	Type	Description
idalways	string	The list’s id.
titlealways	string	Title.
kind	string	`ranked` lists are in order, `collection`s are not, `smart` lists fill themselves. One of: `ranked`, `collection`, `smart`, `collaborative`
visibility	string	Always `public` without credentials.
emoji	string or null	Its emoji. May be empty.
entryCount	integer	How many entries.
updatedAt	string (date-time) or null	When it last changed.

meta (PageMeta)#

Field	Type	Description
apiVersionalways	integer	The API version that answered.
migrationPhase	integer	Internal to Rankd. Ignore it.
sourceOfTruth	string	Internal to Rankd. Ignore it.
nextCursor	string or null	Pass this as `cursor` to get the next page. `null` or missing on the last page.

Responses#

200A page of lists.

Captured from production: GET /v1/users/usr_01KY0JGXMWTT8H9WFN9RTM5JP9/lists?limit=2

200 response

{
  "data": [
    {
      "id": "9c56fe92-4ac1-463d-af4b-bbadfd11e5eb",
      "title": "Songs I don’t rate",
      "kind": "smart",
      "visibility": "public",
      "emoji": "",
      "entryCount": 0,
      "updatedAt": "2026-09-29T20:36:57.231Z"
    },
    {
      "id": "1082404f-6402-437b-a137-89b585754d74",
      "title": "My 5★ Albums",
      "kind": "collection",
      "visibility": "public",
      "emoji": "🌟",
      "entryCount": 14,
      "updatedAt": "2026-09-29T13:15:54.311Z"
    }
  ],
  "meta": {
    "apiVersion": 1,
    "migrationPhase": 3,
    "sourceOfTruth": "per_account",
    "nextCursor": "MTc5MDY4Nzc1NDMxMXwxMDgyNDA0Zi02NDAyLTQzN2ItYTEzNy04OWI1ODU3NTRkNzQ"
  }
}

404No such user, or they are not discoverable.

Captured from production: GET /v1/users/by-username/no_such_person_zz

404 response

{
  "error": {
    "code": "not_found",
    "message": "User not found."
  }
}

429Too many requests this minute. Wait Retry-After seconds, then try again.

Headers: Retry-After Seconds to wait. Always 60.

429 response

{
  "error": "rate limited"
}