# Получить отчёт о диске галактики

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

Возвращает сохранённый отчёт о диске галактики. Запрос не будит хост, не запускает замер и не удаляет данные.

Авторизация: API-ключ, для ключа приложения — сессия пользователя. Передайте идентификатор хоста галактики или приложения текущего ключа. Ключ хоста видит все живые приложения. Ключ приложения видит только приложения того же ключа, даже если остальные ключи принадлежат тому же человеку. Данные остальных приложений объединены в `otherDataMb` без имён и идентификаторов.

## Параметры

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `id` (path) | string (UUID) | Да | Идентификатор хоста галактики или приложения текущего ключа из [списка серверов](./list.md). Хост, на который ссылается приложение ключа, приходит там строкой с `access.via: "galaxy-reference"` |

## Примеры

### curl — личный ключ

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

### curl — OAuth-приложение

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

### JavaScript — личный ключ

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

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/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()
```

## Поля ответа

Все размеры указаны в мебибайтах. Неизвестный размер — `null`, а не ноль.

| Поле | Тип | Описание |
|---|---|---|
| `success` | boolean | Всегда `true` при успехе |
| `data` | object \| null | Сохранённый отчёт. `null` для обычного сервера или если успешного снимка ещё нет |
| `data.measuredAt` | string (ISO 8601) | Время выбранного снимка. Он может быть старше последней попытки замера |
| `data.outcome` | string | `complete` или `partial`: удалось ли выполнить выбранный замер полностью |
| `data.notMeasured` | array of strings | Разделы, которые не удалось измерить в выбранном снимке, например `images` |
| `data.disk` | object | Общие показатели корневой файловой системы |
| `data.disk.totalMb` | number \| null | Полный объём диска |
| `data.disk.usedMb` | number \| null | Занятое место |
| `data.disk.freeMb` | number \| null | Свободное место |
| `data.apps` | array | Видимые живые приложения по убыванию известного размера данных. Неизвестные размеры идут последними |
| `data.apps[].id` | string (UUID) | Идентификатор приложения |
| `data.apps[].name` | string | Отображаемое имя или системное имя, если отображаемое не задано |
| `data.apps[].dataMb` | number \| null | Размер тома приложения. `null`, если в снимке не найден соответствующий том |
| `data.otherDataMb` | number \| null | Данные томов вне видимых приложений, включая удалённые и несопоставленные тома. Порядок расчёта описан ниже |
| `data.imagesMb` | number \| null | Место, занятое образами контейнеров |
| `data.imagesReclaimableMb` | number \| null | Место образов, которое потенциально можно освободить отдельной очисткой |
| `data.buildCacheMb` | number \| null | Размер кеша сборки |
| `data.buildCacheReclaimableMb` | number \| null | Место кеша сборки, которое потенциально можно освободить отдельной очисткой |
| `data.containersWritableMb` | number \| null | Изменяемые слои контейнеров |
| `data.containerLogsMb` | number \| null | Файлы журналов контейнеров |

## Пример ответа

Ключ хоста:

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

Ключ приложения, по идентификатору своего приложения или хоста:

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

Успешного снимка нет или указан обычный сервер:

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

## Пример ответа при ошибке

404 — посторонний ключ получает тот же отказ, что и при [чтении карточки сервера](./get.md):

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

## Ошибки

| HTTP | Код | Условие |
|---|---|---|
| 401 | `MISSING_API_KEY` | В запросе нет API-ключа |
| 401 | `INVALID_API_KEY` | API-ключ недействителен |
| 404 | `NOT_FOUND` | Сервер отсутствует, удалён или недоступен текущему ключу, в том числе при удалённом портале Битрикс24 |
| 429 | `CALLER_RATE_LIMITED` | Превышен предел запросов к API для вызывающего клиента |

Остальные ограничения авторизации и портала описаны в разделе [Ошибки](/docs/errors).

## Известные особенности

- Отчёт берётся из сохранённого снимка. Для спящего хоста остаются последние известные значения. Перед действиями проверяйте `measuredAt`.
- Из двух последних успешных снимков выбирается самый новый с непустым списком томов. Если такого нет, используется последний успешный снимок, даже если он `partial`. Поле `notMeasured` относится именно к выбранному снимку.
- В снимке сохраняется не более 30 самых крупных томов. У приложения вне этого списка или с несопоставленным именем тома будет `dataMb: null`. При известной сумме томов его данные остаются в `otherDataMb`.
- При известной сумме томов `otherDataMb` равен этой сумме за вычетом известных размеров видимых приложений, но не меньше нуля. Если сумма неизвестна, складываются остальные перечисленные тома. Если общий объём томов не измерен и список томов отсутствует или пуст, `otherDataMb` равен `null`.
- Размеры образов и кеша сборки, доступные для освобождения, — оценки, а не свободное место. Запрос ничего не очищает. Занятое место может включать данные вне перечисленных категорий, поэтому их сумма не обязана совпадать с `disk.usedMb`.
- Доступ к хосту через приложение разрешает только чтение. Он не открывает команды, загрузку файлов или управление состоянием хоста. [Операции приложения](/docs/infra/galaxy) по-прежнему вызываются по идентификатору приложения.

## Смотрите также

- [Получить сервер](./get.md)
- [Список серверов](./list.md)
- [Галактики](/docs/infra/galaxy)
