Skip to main content

​
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

​
id
string
required
The container ID or name

​
Query Parameters

​
env
string
required
The environment ID where the container is located

​
Response

​
cpuPercent
number
CPU usage percentage (0-100 per core, can exceed 100 on multi-core systems)
​
memoryUsage
number
Actual memory usage in bytes (excluding cache). This is calculated by subtracting inactive file cache from total usage, matching Docker CLI behavior.
​
memoryRaw
number
Raw memory usage in bytes (including cache)
​
memoryCache
number
File cache size in bytes that was subtracted from raw usage
​
memoryLimit
number
Memory limit in bytes configured for the container
​
memoryPercent
number
Memory usage as a percentage of the limit (0-100)
​
networkRx
number
Total network bytes received across all interfaces
​
networkTx
number
Total network bytes transmitted across all interfaces
​
blockRead
number
Total bytes read from block devices
​
blockWrite
number
Total bytes written to block devices
​
timestamp
number
Unix timestamp in milliseconds when the stats were collected

​
Error Responses

​
error
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"

​
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

​
env
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.
​
id
string
Container ID
​
name
string
Container name
​
cpuPercent
number
CPU usage percentage
​
memoryUsage
number
Actual memory usage in bytes (excluding cache)
​
memoryRaw
number
Raw memory usage in bytes (including cache)
​
memoryCache
number
File cache size in bytes
​
memoryLimit
number
Memory limit in bytes
​
memoryPercent
number
Memory usage percentage
​
networkRx
number
Network bytes received
​
networkTx
number
Network bytes transmitted
​
blockRead
number
Block device bytes read
​
blockWrite
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.
​
error
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"

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us