For AI agents: markdown of this page — /docs-content-en/infra/servers/disk-usage.md documentation index — /llms.txt

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
Parameterid (path) Typestring (UUID) RequiredYes DescriptionGalaxy host ID or the current key's application ID from the server list. A host referenced by the key's application appears there as a row with access.via: "galaxy-reference"

Examples

Personal key: curl

Terminal
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

Terminal
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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject | null DescriptionSaved report. null for a standalone server or when no successful snapshot exists yet
Fielddata.measuredAt Typestring (ISO 8601) DescriptionTime of the selected snapshot, which may be older than the latest measurement attempt
Fielddata.outcome Typestring Descriptioncomplete or partial: whether the selected measurement finished in full
Fielddata.notMeasured Typearray of strings DescriptionSections not measured in the selected snapshot, for example images
Fielddata.disk Typeobject DescriptionRoot filesystem totals
Fielddata.disk.totalMb Typenumber | null DescriptionTotal disk capacity
Fielddata.disk.usedMb Typenumber | null DescriptionUsed disk space
Fielddata.disk.freeMb Typenumber | null DescriptionFree disk space
Fielddata.apps Typearray DescriptionVisible live applications, largest known data size first, unknown sizes last
Fielddata.apps[].id Typestring (UUID) DescriptionApplication ID
Fielddata.apps[].name Typestring DescriptionDisplay name, or the system name when no display name is set
Fielddata.apps[].dataMb Typenumber | null DescriptionApplication volume size. null when the snapshot has no matching volume
Fielddata.otherDataMb Typenumber | null DescriptionVolume data outside the visible applications, including deleted or unmatched volumes. Computation is described below
Fielddata.imagesMb Typenumber | null DescriptionSpace used by container images
Fielddata.imagesReclaimableMb Typenumber | null DescriptionImage space potentially reclaimable by a separate cleanup
Fielddata.buildCacheMb Typenumber | null DescriptionBuild cache size
Fielddata.buildCacheReclaimableMb Typenumber | null DescriptionBuild cache space potentially reclaimable by a separate cleanup
Fielddata.containersWritableMb Typenumber | null DescriptionWritable layers of containers
Fielddata.containerLogsMb Typenumber | null DescriptionContainer 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 route:

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

Errors

HTTP Code Condition
HTTP401 CodeMISSING_API_KEY ConditionThe request has no API key
HTTP401 CodeINVALID_API_KEY ConditionThe API key is invalid
HTTP404 CodeNOT_FOUND ConditionThe server is missing, deleted or inaccessible to this key, including a deleted Bitrix24 portal
HTTP429 CodeCALLER_RATE_LIMITED ConditionThe caller has exceeded the API request limit

Other authentication and account restrictions are described in 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 still use the application ID.

See also