# Get galaxy disk usage

`GET /v1/infra/servers/:id/disk-usage`

Returns the saved disk usage report of a galaxy. The request does not wake the host, start a measurement or delete data.

Authorization: API key, with a user session when using an application key. Use the galaxy host ID or the ID of an application managed by the current key. A host key sees all live applications. An application key sees only applications managed by that same key, even when other keys belong to the same person. Data of other applications is combined into `otherDataMb` without names or IDs.

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` (path) | string (UUID) | Yes | Galaxy host ID or the current key's application ID from the [server list](./list.md). A host referenced by the key's application appears there as a row with `access.via: "galaxy-reference"` |

## Examples

Personal key: curl

```bash
curl 'https://vibecode.bitrix24.com/v1/infra/servers/3f7a91c4-6e0b-42d8-8b55-19ad7c204e6f/disk-usage' \
  -H 'X-Api-Key: YOUR_API_KEY'
```

Application key and user session: curl

```bash
curl 'https://vibecode.bitrix24.com/v1/infra/servers/3f7a91c4-6e0b-42d8-8b55-19ad7c204e6f/disk-usage' \
  -H 'X-Api-Key: YOUR_APP_KEY' \
  -H 'Authorization: Bearer USER_SESSION_TOKEN'
```

Personal key: JavaScript

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/infra/servers/3f7a91c4-6e0b-42d8-8b55-19ad7c204e6f/disk-usage', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
```

Application key and user session: JavaScript

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/infra/servers/3f7a91c4-6e0b-42d8-8b55-19ad7c204e6f/disk-usage', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
```

## Response fields

All sizes are in mebibytes (MiB). An unknown size is `null`, not zero.

| Field | Type | Description |
|---|---|---|
| `success` | boolean | Always `true` on success |
| `data` | object \| null | Saved report. `null` for a standalone server or when no successful snapshot exists yet |
| `data.measuredAt` | string (ISO 8601) | Time of the selected snapshot, which may be older than the latest measurement attempt |
| `data.outcome` | string | `complete` or `partial`: whether the selected measurement finished in full |
| `data.notMeasured` | array of strings | Sections not measured in the selected snapshot, for example `images` |
| `data.disk` | object | Root filesystem totals |
| `data.disk.totalMb` | number \| null | Total disk capacity |
| `data.disk.usedMb` | number \| null | Used disk space |
| `data.disk.freeMb` | number \| null | Free disk space |
| `data.apps` | array | Visible live applications, largest known data size first, unknown sizes last |
| `data.apps[].id` | string (UUID) | Application ID |
| `data.apps[].name` | string | Display name, or the system name when no display name is set |
| `data.apps[].dataMb` | number \| null | Application volume size. `null` when the snapshot has no matching volume |
| `data.otherDataMb` | number \| null | Volume data outside the visible applications, including deleted or unmatched volumes. Computation is described below |
| `data.imagesMb` | number \| null | Space used by container images |
| `data.imagesReclaimableMb` | number \| null | Image space potentially reclaimable by a separate cleanup |
| `data.buildCacheMb` | number \| null | Build cache size |
| `data.buildCacheReclaimableMb` | number \| null | Build cache space potentially reclaimable by a separate cleanup |
| `data.containersWritableMb` | number \| null | Writable layers of containers |
| `data.containerLogsMb` | number \| null | Container log files |

## Response example

Host key:

```json
{
  "success": true,
  "data": {
    "measuredAt": "2026-11-16T09:00:00.000Z",
    "outcome": "complete",
    "notMeasured": [],
    "disk": {
      "totalMb": 1000,
      "usedMb": 700,
      "freeMb": 300
    },
    "apps": [
      {
        "id": "5c2d33e4-9f15-4347-a023-a2e3080c1073",
        "name": "Foreign app",
        "dataMb": 300
      },
      {
        "id": "4b1c22d3-8e04-4236-9912-91d2f7fb0962",
        "name": "My app",
        "dataMb": 100
      }
    ],
    "otherDataMb": 200,
    "imagesMb": 50,
    "imagesReclaimableMb": 10,
    "buildCacheMb": 20,
    "buildCacheReclaimableMb": 15,
    "containersWritableMb": 5,
    "containerLogsMb": 25
  }
}
```

Application key, using either its application ID or the host ID:

```json
{
  "success": true,
  "data": {
    "measuredAt": "2026-11-16T09:00:00.000Z",
    "outcome": "complete",
    "notMeasured": [],
    "disk": {
      "totalMb": 1000,
      "usedMb": 700,
      "freeMb": 300
    },
    "apps": [
      {
        "id": "4b1c22d3-8e04-4236-9912-91d2f7fb0962",
        "name": "My app",
        "dataMb": 100
      }
    ],
    "otherDataMb": 500,
    "imagesMb": 50,
    "imagesReclaimableMb": 10,
    "buildCacheMb": 20,
    "buildCacheReclaimableMb": 15,
    "containersWritableMb": 5,
    "containerLogsMb": 25
  }
}
```

No successful snapshot, or a standalone server:

```json
{
  "success": true,
  "data": null
}
```

## Error response example

404 — an unrelated key receives the same refusal as the [server detail](./get.md) route:

```json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Server not found"
  }
}
```

## Errors

| HTTP | Code | Condition |
|---|---|---|
| 401 | `MISSING_API_KEY` | The request has no API key |
| 401 | `INVALID_API_KEY` | The API key is invalid |
| 404 | `NOT_FOUND` | The server is missing, deleted or inaccessible to this key, including a deleted Bitrix24 portal |
| 429 | `CALLER_RATE_LIMITED` | The caller has exceeded the API request limit |

Other authentication and account restrictions are described in [Errors](/docs/errors).

## Known specifics

- The report uses a saved snapshot. A sleeping host keeps the last known values. Check `measuredAt` before acting on them.
- Of the two most recent successful snapshots, the newer one with a non-empty volume list is selected. If neither has one, the latest successful snapshot is used, even when it is `partial`. `notMeasured` describes that selected snapshot.
- The snapshot saves at most 30 of the largest volumes. An application outside that list, or with an unmatched volume name, has `dataMb: null`. Its data remains in `otherDataMb` when the volume total is known.
- With a known volume total, `otherDataMb` is that total minus the visible applications' known sizes, with a minimum of zero. Without a total, it is the sum of other listed volumes. If the volume total has not been measured and the volume list is absent or empty, `otherDataMb` is `null`.
- Image and build cache reclaimable sizes are estimates, not free space. The request performs no cleanup. Disk usage can include data outside the listed categories, so the categories need not add up to `disk.usedMb`.
- Host access through an application is read-only. It does not allow host commands, uploads or lifecycle operations. [Application operations](/docs/infra/galaxy) still use the application ID.

## See also

- [Get a server](./get.md)
- [List servers](./list.md)
- [Galaxy](/docs/infra/galaxy)
