---
url: https://milthm.cn/wiki/en/manual/developer/milkloud/user-scores.md
description: Read recent score activity, Reality, and best performances from Milkloud.
---

# Recent Scores and Rank

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

## Recent Scores

```http
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:

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

export type RecentResponse = MilkloudResponse<UserRecentInfo>;
```

## Reality and Best Performances

```http
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:

```ts
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:

```ts
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](https://milthm.cn/wiki/en/manual/developer/milkloud/errors.md#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.