Discovery

Community feed

GET/v1/feed/for-you

No API keyRate-limitedPaginated

The community feed. Without credentials it is the same for everyone, and meta.personalized is false. Cards come in several types, each with its own fields. Skip types your client does not know: new ones are added without a new API version.

Parameters#

Query parameters#

Name	Type	Description
limit	integer default 20	How many items to return. Default 20, at most 40. Larger values are capped at 40; 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/feed/for-you"

const response = await fetch('https://api.rankdmusic.app/v1/feed/for-you');
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/feed/for-you")!
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/feed/for-you", 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 FeedCard objects, and meta is a FeedMeta.

Field	Type	Description
idalways	string	The card’s stable id.
typealways	string	What kind of card. Today: `rating`, `review`, `list`, `trending`, `new_release`, `insight` and `suggested_users`. More can be added.
createdAt	string (date-time) or null	When the thing it shows happened.
reason	string or null	Why it is in the feed, for display.
actor	object	Who did it, on cards about someone’s activity.
id	string	User id.
username	string	Username.
displayName	string or null	Display name.
avatarUrl	string or null	Profile picture.
music	MusicSummary
value	integer or null	On `rating` and `review` cards: the rating, 0–100. `null` for a review given without one.
review	object	On `review` cards: the review.
session	object or null	On `rating` cards: other ratings made at the same sitting.
users	array of object	On `suggested_users` cards: the people suggested.
insight	object	On `insight` cards: the insight.
list	object	On `list` cards: the list.
stats	object	On `trending` and `new_release` cards: its numbers.
period	string	On `trending` and `new_release` cards: the period it covers.
activityId	string or null	The activity the card shows, when it shows one.
engagement	object	Counts of reactions and comments.

meta (FeedMeta)#

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` for the next page. `null` at the end.
personalized	boolean	Whether the feed is shaped by the caller’s own taste. Always `false` without credentials.
coldStart	boolean	Whether this is the general community ranking rather than a feed shaped by who the caller follows.

Responses#

200A page of feed cards.

Captured from production: GET /v1/feed/for-you?limit=40

200 response

{
  "data": [
    {
      "id": "list:1082404f-6402-437b-a137-89b585754d74",
      "type": "list",
      "createdAt": "2026-09-29T13:15:54.311Z",
      "actor": {
        "id": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9",
        "username": "kyle",
        "displayName": "kyle",
        "avatarUrl": "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4"
      },
      "list": {
        "id": "1082404f-6402-437b-a137-89b585754d74",
        "title": "My 5★ Albums",
        "description": "",
        "emoji": "🌟",
        "kind": "collection",
        "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"
        ]
      },
      "engagement": {
        "reactions": 0,
        "comments": 0,
        "likes": 0,
        "saves": 0
      },
      "reason": "Community list"
    },
    {
      "id": "trending:album:697194953",
      "type": "trending",
      "createdAt": "2026-09-30T11:14:42.530Z",
      "music": {
        "type": "album",
        "id": "697194953",
        "title": "Discovery",
        "artistName": "Daft Punk",
        "albumId": null,
        "albumTitle": null,
        "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/{w}x{h}bb.jpg",
        "releaseYear": 2001,
        "genre": "Dance"
      },
      "stats": {
        "raters": 4,
        "average": 98,
        "thisWeek": 2
      },
      "period": "this month",
      "reason": "Trending on Rankd"
    }
  ],
  "meta": {
    "apiVersion": 1,
    "migrationPhase": 3,
    "sourceOfTruth": "per_account",
    "nextCursor": null,
    "personalized": false,
    "coldStart": true
  }
}

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