Search lists

GET/v1/search/lists

No API keyRate-limited

Finds public lists by title, description or who made them.

Parameters#

Query parameters#

Name	Type	Description
qrequired	string	At least two characters. Example: `albums`
limit	integer default 25	How many items to return. Default 25, at most 50. Larger values are capped at 50; anything that is not a positive whole number gives the default.

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/search/lists?q=albums"

const response = await fetch('https://api.rankdmusic.app/v1/search/lists?q=albums');
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/search/lists?q=albums")!
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/search/lists?q=albums", 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 an array of ListResult objects, and meta is a Meta.

Field	Type	Description
idalways	string	The list’s id.
ownerUsername	string	Who made it.
ownerName	string or null	Their display name.
titlealways	string	Title.
kind	string	`ranked`, `collection`, `smart` or `collaborative`.
emoji	string or null	Its emoji. May be empty.
entryCount	integer	How many entries.
covers	array of string	Artwork templates (`{w}x{h}`) of its first entries.
updatedAt	string (date-time) or null	When it last changed.

Responses#

200Matching public lists.

Captured from production: GET /v1/search/lists?q=albums&limit=10

200 response

{
  "data": [
    {
      "id": "b218ac44-4233-4230-ae9e-ecf31ea4b5b6",
      "ownerUsername": "kyle",
      "ownerName": "kyle",
      "title": "Albums I Love!",
      "kind": "ranked",
      "emoji": "",
      "entryCount": 16,
      "covers": [
        "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/1d/1b/f9/1d1bf9b1-44c6-9a6c-6ffb-c158488c06ce/26UMGIM39303.rgb.jpg/{w}x{h}bb.jpg",
        "https://is1-ssl.mzstatic.com/image/thumb/Music125/v4/37/ae/95/37ae95a0-2e1c-bf03-4900-983686da9292/12UMGIM00033.rgb.jpg/{w}x{h}bb.jpg"
      ],
      "updatedAt": "2026-07-23T14:19:54.728Z"
    },
    {
      "id": "1082404f-6402-437b-a137-89b585754d74",
      "ownerUsername": "kyle",
      "ownerName": "kyle",
      "title": "My 5★ Albums",
      "kind": "collection",
      "emoji": "🌟",
      "entryCount": 14,
      "covers": [
        "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/58/8f/a9/588fa9a2-7cc5-f02c-9ce6-c986e0dc1c15/25UM1IM19577.rgb.jpg/{w}x{h}bb.jpg",
        "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/eb/e6/06/ebe606da-e00f-82d3-47f3-b79904eed541/17UM1IM24651.rgb.jpg/{w}x{h}bb.jpg"
      ],
      "updatedAt": "2026-09-29T13:15:54.311Z"
    }
  ],
  "meta": {
    "apiVersion": 1,
    "migrationPhase": 3,
    "sourceOfTruth": "per_account"
  }
}

400q is shorter than two characters.

Captured from production: GET /v1/music/search?q=a

400 response

{
  "error": {
    "code": "invalid_query",
    "message": "Search for at least two characters."
  }
}

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"
}