Lists

Get a list

GET/v1/lists/{listId}

No API keyRate-limited

A public list with its entries in order (up to 500).

Parameters#

Path parameters#

Name	Type	Description
listIdrequired	string	The list’s id, a UUID. Pattern: `^[0-9a-f-]{36}$` · Example: `1082404f-6402-437b-a137-89b585754d74`

Query parameters#

Name	Type	Description
owner	string	The owner’s username. Rankd share links include it. It picks the right list when the id is one the app gave the list and more than one person has a list with that id.

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/lists/1082404f-6402-437b-a137-89b585754d74"

const response = await fetch('https://api.rankdmusic.app/v1/lists/1082404f-6402-437b-a137-89b585754d74');
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;

import Foundation

let url = URL(string: "https://api.rankdmusic.app/v1/lists/1082404f-6402-437b-a137-89b585754d74")!
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"]

import requests

response = requests.get("https://api.rankdmusic.app/v1/lists/1082404f-6402-437b-a137-89b585754d74", 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"]

Response#

A successful response is { "data": …, "meta": … }. data is a List, and meta is a Meta.

Field	Type	Description
idalways	string	The list’s id.
clientId	string or null	The id the app gave it. Usually the same as `id`.
ownerUserId	string	Who made it.
ownerUsername	string	Their username.
titlealways	string	Title.
description	string or null	Description.
kind	string	`ranked`, `collection`, `smart` or `collaborative`. One of: `ranked`, `collection`, `smart`, `collaborative`
visibility	string	Always `public` without credentials.
emoji	string or null	Emoji. May be empty.
icon	string or null	The SF Symbol name Rankd’s apps draw for it.
theme	string or null	The colour theme Rankd’s apps draw it in.
category	string or null	Category. May be empty.
tags	array of string
createdAt	string (date-time) or null	Created.
updatedAt	string (date-time) or null	Last changed.
entriesalways	array of object	In order.
position	integer	Position, from 0.
note	string or null	The owner’s note on this entry.
music	MusicRef

Responses#

200The list.

Captured from production: GET /v1/lists/1082404f-6402-437b-a137-89b585754d74

200 response

{
  "data": {
    "id": "1082404f-6402-437b-a137-89b585754d74",
    "clientId": "1082404f-6402-437b-a137-89b585754d74",
    "ownerUserId": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9",
    "ownerUsername": "kyle",
    "title": "My 5★ Albums",
    "description": "",
    "kind": "collection",
    "visibility": "public",
    "emoji": "🌟",
    "icon": "wand.and.stars",
    "theme": "gold",
    "category": "",
    "tags": [],
    "createdAt": "2026-07-23T20:36:17.877Z",
    "updatedAt": "2026-09-29T13:15:54.311Z",
    "entries": [
      {
        "position": 0,
        "note": "",
        "music": {
          "provider": "apple_music",
          "type": "album",
          "id": "1838810949",
          "title": "The Life of a Showgirl",
          "artistName": "Taylor Swift",
          "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/58/8f/a9/588fa9a2-7cc5-f02c-9ce6-c986e0dc1c15/25UM1IM19577.rgb.jpg/600x600bb.jpg",
          "albumId": null,
          "albumTitle": null
        }
      },
      {
        "position": 1,
        "note": "",
        "music": {
          "provider": "apple_music",
          "type": "album",
          "id": "1440933849",
          "title": "reputation",
          "artistName": "Taylor Swift",
          "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/eb/e6/06/ebe606da-e00f-82d3-47f3-b79904eed541/17UM1IM24651.rgb.jpg/600x600bb.jpg",
          "albumId": null,
          "albumTitle": null
        }
      }
    ]
  },
  "meta": {
    "apiVersion": 1,
    "migrationPhase": 3,
    "sourceOfTruth": "per_account"
  }
}

404No such list, or it is private.

Captured from production: GET /v1/lists/00000000-0000-0000-0000-000000000000

404 response

{
  "error": {
    "code": "not_found",
    "message": "List 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"
}