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
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
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
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
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:
{
"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:
{
"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:
{
"success": true,
"data": null
}
Error response example
404 — an unrelated key receives the same refusal as the server detail route:
{
"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
measuredAtbefore 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.notMeasureddescribes 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 inotherDataMbwhen the volume total is known. - With a known volume total,
otherDataMbis 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,otherDataMbisnull. - 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.