Guides

Quickstart

Four requests take you from a Rankd username to every rating that person has made public. You need nothing but an HTTP client.

1. Check the API#

Start with the health check. data.database is "ok" when the API can reach its data.

cURL

curl https://api.rankdmusic.app/v1/health

Response

{
  "data": {
    "database": "ok"
  },
  "meta": {
    "apiVersion": 1,
    "migrationPhase": 3,
    "sourceOfTruth": "per_account"
  }
}

Every successful response has the same two keys: data, the thing you asked for, and meta, which says which API version answered. meta has two more fields, migrationPhase and sourceOfTruth. They are internal to Rankd; ignore them.

2. Find someone#

Profiles are addressed by user id. To get from a username to an id, use Look up a user by username:

cURL

curl https://api.rankdmusic.app/v1/users/by-username/kyle

Response

{
  "data": {
    "id": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9",
    "username": "kyle",
    "displayName": "kyle",
    "avatarUrl": "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4",
    "isDiscoverable": true
  },
  "meta": {
    "apiVersion": 1,
    "migrationPhase": 3,
    "sourceOfTruth": "per_account"
  }
}

Only people who chose to be discoverable in Rankd can be found. Anyone else answers 404, exactly as if they did not exist.

3. Read their ratings#

A user’s ratings returns their public ratings, most recently changed first. A rating’s value is a whole number from 0 to 100: divide by 20 for stars.

cURL

curl "https://api.rankdmusic.app/v1/users/usr_01KY0JGXMWTT8H9WFN9RTM5JP9/ratings?limit=2"

Response

{
  "data": [
    {
      "id": "rat_01M3QSX2M2ESSG165BGJWYM5ZS",
      "music": {
        "provider": "apple_music",
        "type": "song",
        "id": "697195462",
        "title": "One More Time",
        "artistName": "Daft Punk",
        "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg",
        "albumId": "697194953",
        "albumTitle": "Discovery"
      },
      "value": 80,
      "visibility": "public",
      "createdAt": "2026-09-30T00:02:19.906Z",
      "createdAtPrecision": "exact",
      "updatedAt": "2026-09-30T00:02:19.906Z"
    },
    {
      "id": "rat_01M3EZRBAW621QVN73BHKENP8B",
      "music": {
        "provider": "apple_music",
        "type": "song",
        "id": "6814997428",
        "title": "Pink Clouding",
        "artistName": "Taylor Swift",
        "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/600x600bb.jpg",
        "albumId": "6814997249",
        "albumTitle": "The Life of a Showgirl: The Encore"
      },
      "value": 100,
      "visibility": null,
      "createdAt": "2026-09-26T13:51:26.556Z",
      "createdAtPrecision": "exact",
      "updatedAt": "2026-09-29T23:40:53.152Z"
    }
  ],
  "meta": {
    "apiVersion": 1,
    "migrationPhase": 3,
    "sourceOfTruth": "per_account",
    "nextCursor": "MTc5MDcyNTI1MzE1MnxyYXRfMDFNM0VaUkJBVzYyMVFWTjczQkhLRU5QOEI"
  }
}

4. Page through the rest#

When there is more, meta.nextCursor is set. Send it back as cursor until it comes back null:

const user = 'usr_01KY0JGXMWTT8H9WFN9RTM5JP9';
let cursor = null;
const ratings = [];

do {
  const url = new URL(`https://api.rankdmusic.app/v1/users/${user}/ratings`);
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);

  const response = await fetch(url);
  if (!response.ok) throw new Error(`Rankd API: ${response.status}`);
  const { data, meta } = await response.json();

  ratings.push(...data);
  cursor = meta.nextCursor ?? null;
} while (cursor);

console.log(`${ratings.length} public ratings`);

import requests

user = "usr_01KY0JGXMWTT8H9WFN9RTM5JP9"
ratings, cursor = [], None

while True:
    params = {"limit": 100}
    if cursor:
        params["cursor"] = cursor
    response = requests.get(f"https://api.rankdmusic.app/v1/users/{user}/ratings", params=params, timeout=10)
    response.raise_for_status()
    body = response.json()
    ratings += body["data"]
    cursor = body["meta"].get("nextCursor")
    if not cursor:
        break

print(len(ratings), "public ratings")

Paging quickly through a big profile uses up the rate limit fast: 60 requests a minute. Use the largest limit the endpoint allows, and see Rate limits for handling 429.

Where next#

Look up an album and its reviews with Get an album, song or artist and Reviews of an album, song or artist.
Show this week’s chart with Rankd Charts.
Handle failures properly: Errors.