hzel Docs

ContainerRecord is the canonical representation of a container returned by every container endpoint — create, list, get, start, stop, and restart.

Fields

Field	Type	Description
`id`	`string (UUID)`	Unique container identifier.
`proxmox_ctid`	`integer`	Proxmox LXC container ID (CT ID) assigned on the Proxmox node.
`name`	`string`	The hostname / display name given at creation time.
`node_name`	`string`	Hostname of the Proxmox node the container was provisioned on (e.g. `"pve01"`).
`cpu_cores`	`integer`	Provisioned vCPU count (stored as `i16`).
`memory_mb`	`integer`	Provisioned RAM in MiB (stored as `i32`).
`disk_gb`	`integer`	Provisioned disk in GiB (stored as `i32`).
`state`	`string`	Lifecycle state. One of `"provisioning"`, `"running"`, `"stopped"`, `"failed"`.
`created_at`	`string (ISO 8601)`	UTC timestamp when the container record was created.

State values

Value	Meaning
`"provisioning"`	Container is being allocated and configured on the Proxmox node.
`"running"`	Container is live and accepting connections.
`"stopped"`	Container is present but not running.
`"failed"`	A lifecycle action (start, stop, restart) could not be confirmed within the polling timeout.

Example

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "proxmox_ctid": 102,
  "name": "my-box",
  "node_name": "pve01",
  "cpu_cores": 1,
  "memory_mb": 512,
  "disk_gb": 18,
  "state": "running",
  "created_at": "2025-06-15T12:00:00Z"
}

ContainerMetrics

Returned by GET /api/v1/containers/{id}/metrics. A point-in-time snapshot of runtime resource usage.

Field	Type	Description
`cpu_percent`	`number (float)`	CPU utilisation percentage from 0 to 100.
`memory_used_mb`	`integer`	RAM currently in use, in MiB (stored as `u32`).
`memory_limit_mb`	`integer`	Provisioned RAM limit, in MiB (stored as `u32`).
`network_rx_bytes`	`integer`	Cumulative bytes received since the container last started (stored as `u64`).
`network_tx_bytes`	`integer`	Cumulative bytes transmitted since the container last started (stored as `u64`).

{
  "cpu_percent": 3.2,
  "memory_used_mb": 128,
  "memory_limit_mb": 512,
  "network_rx_bytes": 1048576,
  "network_tx_bytes": 524288
}