---
url: https://milthm.cn/wiki/en/manual/developer/milkloud/cloud-save.md
description: Read Milkloud cloud-save metadata and request a download URL.
---

# Cloud Save

The Cloud Save API lets an authenticated user inspect their own save summary and request a URL for the save file.
Both endpoints require `milthm:save:read`.

## Save Metadata

```http
GET /v1/game/save/info
Authorization: Bearer ACCESS_TOKEN
```

The response data has this shape:

```ts
export interface SaveInfo {
    meta: string;
    updated_at: string;
}
```

`updated_at` is an RFC 3339 timestamp. `meta` is a JSON document encoded as a string, so parse `data.meta` separately.

### Save Metadata Fields

```ts
export interface SaveInfoMeta {
    m_count: number;
    ss_count: number;
    s_count: number;
    a_count: number;
    b_count: number;
    c_count: number;
    f_count: number;

    rr_count: number;
    ap_count: number;
    fc_count: number;
    complete_count: number;

    date: string;
    hash: string;
    installation_id: string;
    reality_value: number;
}
```

| Field                       | Description                                   |
|-----------------------------|-----------------------------------------------|
| `m_count` through `f_count` | Counts for each recorded grade.               |
| `rr_count`                  | Count of Rhythm of Rain results.              |
| `ap_count`                  | Count of All Perfect results.                 |
| `fc_count`                  | Count of Full Combo results.                  |
| `complete_count`            | Count of completed records.                   |
| `date`                      | RFC 3339 timestamp recorded in the metadata.  |
| `hash`                      | Save hash recorded by Milthm.                 |
| `installation_id`           | Installation identifier recorded by Milthm.   |
| `reality_value`             | Reality value recorded with the save summary. |

The metadata is a summary, not the save file itself.

## Download URL

```http
GET /v1/game/save
Authorization: Bearer ACCESS_TOKEN
```

Response type:

```ts
export interface DownloadSave {
    file_url: string;
}
```

Each user can request a download URL up to five times per calendar day. Calling this endpoint to obtain a URL consumes
one request; downloading from the returned URL does not request another URL from this endpoint.

Treat `file_url` as sensitive and temporary. Use it promptly, do not publish it, and do not store it in logs.

## 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 metadata or request a URL | `404`       | `GameSaveEmptyError`                 | The current user has no cloud save available.                                            |
| Request a URL                  | `429`       | `GameSaveDownloadLimitExceededError` | The user has exceeded the five daily URL requests. Wait for the next daily quota period. |