Users

Look up a user by username

GET/v1/users/by-username/{username}

No API keyRate-limited

The user behind a username: how to get from a Rankd username to a user id. Only discoverable people are found.

Parameters#

Path parameters#

Name	Type	Description
usernamerequired	string	A Rankd username: up to 20 letters, digits and underscores. Case does not matter. Pattern: `^[A-Za-z0-9_]{1,20}$` · Example: `kyle`

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/by-username/kyle"

const response = await fetch('https://api.rankdmusic.app/v1/users/by-username/kyle');
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/users/by-username/kyle")!
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/users/by-username/kyle", 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 User, and meta is a Meta.

Field	Type	Description
idalways	string	The user’s id.
usernamealways	string	Their username.
displayName	string or null	The name they show.
bio	string or null	Their bio.
foundingMember	FoundingMember
avatarAssetId	string or null	Their profile picture, as an asset id.
avatarUrl	string or null	Their profile picture’s URL.
isDiscoverable	boolean	Whether people who are not signed in can find them.
createdAt	string (date-time) or null	When they joined.
updatedAt	string (date-time) or null	When their profile last changed.

Responses#

200The user.

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

200 response

{
  "data": {
    "id": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9",
    "username": "kyle",
    "displayName": "kyle",
    "bio": "🏴󠁧󠁢󠁳󠁣󠁴󠁿",
    "foundingMember": {
      "number": 2,
      "grantedAt": "2026-09-17T14:44:05.000Z"
    },
    "avatarAssetId": "ast_9E07Q6Q598DXKRQBN0NDSCQYA4",
    "avatarUrl": "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4",
    "isDiscoverable": true,
    "createdAt": "2026-07-20T20:12:20.508Z",
    "updatedAt": "2026-09-29T11:24:06.862Z"
  },
  "meta": {
    "apiVersion": 1,
    "migrationPhase": 3,
    "sourceOfTruth": "per_account"
  }
}

400Not something a Rankd username can be.

400 response

{
  "error": {
    "code": "invalid_username",
    "message": "Invalid username."
  }
}

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