Container Statistics

Get Container Stats

GET /api/containers/{id}/stats?env=1

Retrieves a single snapshot of resource usage statistics for a specific container, including CPU, memory, network, and block I/O metrics.

Path Parameters

string

required

The container ID or name

Query Parameters

string

required

The environment ID where the container is located

Response

number

CPU usage percentage (0-100 per core, can exceed 100 on multi-core systems)

number

Actual memory usage in bytes (excluding cache). This is calculated by subtracting inactive file cache from total usage, matching Docker CLI behavior.

number

Raw memory usage in bytes (including cache)

number

File cache size in bytes that was subtracted from raw usage

number

Memory limit in bytes configured for the container

number

Memory usage as a percentage of the limit (0-100)

number

Total network bytes received across all interfaces

number

Total network bytes transmitted across all interfaces

number

Total bytes read from block devices

number

Total bytes written to block devices

number

Unix timestamp in milliseconds when the stats were collected

Error Responses

string

Error message if the request fails

Status Codes:

200 - Success
403 - Permission denied
404 - Container not found or environment not found
500 - Failed to get stats

Example

curl -X GET "https://your-dockhand.com/api/containers/abc123def456/stats?env=1" \
  -H "Cookie: session=your-session-cookie"

const containerId = 'abc123def456';
const response = await fetch(`/api/containers/${containerId}/stats?env=1`, {
  method: 'GET',
  credentials: 'include'
});

const stats = await response.json();
console.log(`CPU: ${stats.cpuPercent}%`);
console.log(`Memory: ${(stats.memoryUsage / 1024 / 1024).toFixed(2)} MB`);

Response Example

{
  "cpuPercent": 12.45,
  "memoryUsage": 52428800,
  "memoryRaw": 58720256,
  "memoryCache": 6291456,
  "memoryLimit": 2147483648,
  "memoryPercent": 2.44,
  "networkRx": 1048576,
  "networkTx": 524288,
  "blockRead": 4194304,
  "blockWrite": 2097152,
  "timestamp": 1705320600000
}

Stream All Container Stats

GET /api/containers/stats/stream?env=1

Streams resource statistics for all running containers in an environment using Server-Sent Events (SSE). This endpoint collects stats for all containers once and closes the connection.

Query Parameters

string

required

The environment ID to monitor

Response Format

The endpoint returns a Server-Sent Events (SSE) stream with the following event types: Event: stat Emitted for each running container with its statistics.

string

Container ID

string

Container name

number

CPU usage percentage

number

Actual memory usage in bytes (excluding cache)

number

Raw memory usage in bytes (including cache)

number

File cache size in bytes

number

Memory limit in bytes

number

Memory usage percentage

number

Network bytes received

number

Network bytes transmitted

number

Block device bytes read

number

Block device bytes written

Event: done Emitted when all container stats have been collected and the stream is ending. Event: error Emitted if an error occurs during stats collection.

string

Error message

Error Responses

Status Codes:

200 - SSE stream established
403 - Permission denied

Example

curl -X GET "https://your-dockhand.com/api/containers/stats/stream?env=1" \
  -H "Cookie: session=your-session-cookie" \
  -H "Accept: text/event-stream"

const eventSource = new EventSource('/api/containers/stats/stream?env=1');

eventSource.addEventListener('stat', (event) => {
  const stat = JSON.parse(event.data);
  console.log(`${stat.name}: CPU ${stat.cpuPercent}%, Memory ${stat.memoryPercent}%`);
});

eventSource.addEventListener('done', () => {
  console.log('Stats collection complete');
  eventSource.close();
});

eventSource.addEventListener('error', (event) => {
  const error = JSON.parse(event.data);
  console.error('Error:', error.error);
  eventSource.close();
});

Response Example

event: stat
data: {"id":"abc123","name":"my-nginx","cpuPercent":5.23,"memoryUsage":52428800,"memoryRaw":58720256,"memoryCache":6291456,"memoryLimit":2147483648,"memoryPercent":2.44,"networkRx":1048576,"networkTx":524288,"blockRead":4194304,"blockWrite":2097152}

event: stat
data: {"id":"def456","name":"postgres","cpuPercent":15.67,"memoryUsage":209715200,"memoryRaw":220200960,"memoryCache":10485760,"memoryLimit":4294967296,"memoryPercent":4.88,"networkRx":2097152,"networkTx":1048576,"blockRead":8388608,"blockWrite":4194304}

event: done
data: {}

Notes

The stream automatically closes after collecting stats for all containers once
Only running containers are included in the stats collection
Keepalive comments are sent every 5 seconds to maintain the connection
Individual container stats collection has an 8-second timeout
The overall container list fetch has a 10-second timeout
Failed containers are silently skipped

API Overview

Container Management

Stack Management

Image Management

Network & Volume

Environment Management

Scheduling & Automation

Container Statistics

Get Container Stats

Path Parameters

Query Parameters

Response

Error Responses

Example

Response Example

Stream All Container Stats

Query Parameters

Response Format

Error Responses

Example

Response Example

Notes

​Get Container Stats

​Path Parameters

​Query Parameters

​Response

​Error Responses

​Example

​Response Example

​Stream All Container Stats

​Query Parameters

​Response Format

​Error Responses

​Example

​Response Example

​Notes

Get Container Stats

Path Parameters

Query Parameters

Response

Error Responses

Example

Response Example

Stream All Container Stats

Query Parameters

Response Format

Error Responses

Example

Response Example

Notes