Recent Scores and Rank

Milkloud exposes recent score activity and rank information through user-scoped endpoints.

Recent Scores

GET /v1/user/:username/recent
Authorization: Bearer ACCESS_TOKEN

The credential must belong to the requested user and have milthm:event:recent. The endpoint returns at most the 20 most recent score submissions or synchronizations created during the last 72 hours, ordered newest first.

Parameter	Location	Required	Default	Description
username	Path	Yes	None	A URL-encoded username or UID:<uid>.

The response envelope contains a UserRecentInfo object, whose data field is the score list:

export interface UserRecentInfo {
    data?: ScoreResponse[];
}

export type RecentResponse = MilkloudResponse<UserRecentInfo>;

Reality and Best Performances

GET /v1/user/:username/rank
Authorization: Bearer ACCESS_TOKEN

For the current user, milthm:stats:best_performance grants access to private Reality values and best-performance lists. When reading another user, Reality is returned only if that user made it public; another user's best-performance lists are not returned.

Parameter	Location	Required	Default	Description
username	Path	Yes	None	A URL-encoded username or UID:<uid>.
ranks	Query	No	true	Whether to include best-performance lists. Use false or 0 to return only Reality values.

Response type:

export interface UserRankInfo {
    touch_reality?: number;
    keyboard_reality?: number;
    touch_ranks?: ScoreResponse[];
    keyboard_ranks?: ScoreResponse[];
}

export type RankResponse = MilkloudResponse<UserRankInfo>;

Fields are optional. A field is omitted when the requested data is not available or the credential is not allowed to read it.

Score Type

Recent and best-performance lists use the same score type:

export interface ScoreResponse {
    chart_id: string;
    chart_hash: string;
    chart_env: string;
    game_version: string;
    modifiers: string[];
    grade: string;
    score: number;
    score_accuracy: number;
    score_exact_count: number;
    score_perfect_count: number;
    score_great_count: number;
    score_good_count: number;
    score_bad_count: number;
    score_miss_count: number;
    score_fracture_exact_count: number;
    score_fracture_miss_count: number;
    played_at: string;
    extra_info: string;
    score_id: string;
    user_id: string;
    username: string;
    nickname: string;
    replay_id: string;
    reality: number;
}

score_accuracy is in the range from 0 to 1. played_at is an RFC 3339 timestamp. A replay ID may be empty when no replay is available or the caller cannot access it.

Errors

Both endpoints may return the common authentication errors.

Operation	HTTP status	Code	Meaning
Read recent scores or rank	404	UserNotFoundError	The requested user does not exist or the account is no longer available.
Read recent scores	403	PermissionError	The credential does not belong to the requested user or lacks milthm:event:recent.

The rank endpoint does not return an error merely because a Reality value or best-performance list is private. It omits fields that the credential cannot read.