Get container stats based on resource usage Run in API Explorer

GET /containers/{id}/stats

This endpoint returns a live stream of a container’s resource usage statistics.

The precpu_stats is the CPU statistic of the previous read, and is used to calculate the CPU usage percentage. It is not an exact copy of the cpu_stats field.

If either precpu_stats.online_cpus or cpu_stats.online_cpus is nil then for compatibility with older daemons the length of the corresponding cpu_usage.percpu_usage array should be used.

On a cgroup v2 host, the following fields are not set

  • blkio_stats: all fields other than io_service_bytes_recursive
  • cpu_stats: cpu_usage.percpu_usage
  • memory_stats: max_usage and failcnt Also, memory_stats.stats fields are incompatible with cgroup v1.

To calculate the values shown by the stats command of the docker cli tool the following formulas can be used:

  • used_memory = memory_stats.usage - memory_stats.stats.cache
  • available_memory = memory_stats.limit
  • Memory usage % = (used_memory / available_memory) * 100.0
  • cpu_delta = cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage
  • system_cpu_delta = cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage
  • number_cpus = length(cpu_stats.cpu_usage.percpu_usage) or cpu_stats.online_cpus
  • CPU usage % = (cpu_delta / system_cpu_delta) * number_cpus * 100.0

Path parameters

  • id string Required

    ID or name of the container

Query parameters

  • stream boolean

    Stream the output. If false, the stats will be output once and then it will disconnect.

    Default value is true.

  • one-shot boolean

    Only get a single stat instead of waiting for 2 cycles. Must be used with stream=false.

    Default value is false.

Responses

  • 200 application/json

    no error

    Hide response attributes Show response attributes object
    • name string

      Name of the container

    • id string

      ID of the container

    • read string(date-time)

      Date and time at which this sample was collected. The value is formatted as RFC 3339 with nano-seconds.

    • preread string(date-time)

      Date and time at which this first sample was collected. This field is not propagated if the "one-shot" option is set. If the "one-shot" option is set, this field may be omitted, empty, or set to a default date (0001-01-01T00:00:00Z).

      The value is formatted as RFC 3339 with nano-seconds.

    • pids_stats object

      PidsStats contains Linux-specific stats of a container's process-IDs (PIDs).

      This type is Linux-specific and omitted for Windows containers.

      Hide pids_stats attributes Show pids_stats attributes object
      • current integer(uint64)

        Current is the number of PIDs in the cgroup.

      • limit integer(uint64)

        Limit is the hard limit on the number of pids in the cgroup. A "Limit" of 0 means that there is no limit.

    • blkio_stats object

      BlkioStats stores all IO service stats for data read and write.

      This type is Linux-specific and holds many fields that are specific to cgroups v1. On a cgroup v2 host, all fields other than io_service_bytes_recursive are omitted or null.

      This type is only populated on Linux and omitted for Windows containers.

      Hide blkio_stats attributes Show blkio_stats attributes object
      • io_service_bytes_recursive array[object]

        Blkio stats entry.

        This type is Linux-specific and omitted for Windows containers.

        Hide io_service_bytes_recursive attributes Show io_service_bytes_recursive attributes object
        • major integer(uint64)
        • minor integer(uint64)
        • op string
        • value integer(uint64)
      • io_serviced_recursive array[object]

        This field is only available when using Linux containers with cgroups v1. It is omitted or null when using cgroups v2.

        Blkio stats entry.

        This type is Linux-specific and omitted for Windows containers.

        Hide io_serviced_recursive attributes Show io_serviced_recursive attributes object
        • major integer(uint64)
        • minor integer(uint64)
        • op string
        • value integer(uint64)
      • io_queue_recursive array[object]

        This field is only available when using Linux containers with cgroups v1. It is omitted or null when using cgroups v2.

        Blkio stats entry.

        This type is Linux-specific and omitted for Windows containers.

        Hide io_queue_recursive attributes Show io_queue_recursive attributes object
        • major integer(uint64)
        • minor integer(uint64)
        • op string
        • value integer(uint64)
      • io_service_time_recursive array[object]

        This field is only available when using Linux containers with cgroups v1. It is omitted or null when using cgroups v2.

        Blkio stats entry.

        This type is Linux-specific and omitted for Windows containers.

        Hide io_service_time_recursive attributes Show io_service_time_recursive attributes object
        • major integer(uint64)
        • minor integer(uint64)
        • op string
        • value integer(uint64)
      • io_wait_time_recursive array[object]

        This field is only available when using Linux containers with cgroups v1. It is omitted or null when using cgroups v2.

        Blkio stats entry.

        This type is Linux-specific and omitted for Windows containers.

        Hide io_wait_time_recursive attributes Show io_wait_time_recursive attributes object
        • major integer(uint64)
        • minor integer(uint64)
        • op string
        • value integer(uint64)
      • io_merged_recursive array[object]

        This field is only available when using Linux containers with cgroups v1. It is omitted or null when using cgroups v2.

        Blkio stats entry.

        This type is Linux-specific and omitted for Windows containers.

        Hide io_merged_recursive attributes Show io_merged_recursive attributes object
        • major integer(uint64)
        • minor integer(uint64)
        • op string
        • value integer(uint64)
      • io_time_recursive array[object]

        This field is only available when using Linux containers with cgroups v1. It is omitted or null when using cgroups v2.

        Blkio stats entry.

        This type is Linux-specific and omitted for Windows containers.

        Hide io_time_recursive attributes Show io_time_recursive attributes object
        • major integer(uint64)
        • minor integer(uint64)
        • op string
        • value integer(uint64)
      • sectors_recursive array[object]

        This field is only available when using Linux containers with cgroups v1. It is omitted or null when using cgroups v2.

        Blkio stats entry.

        This type is Linux-specific and omitted for Windows containers.

        Hide sectors_recursive attributes Show sectors_recursive attributes object
        • major integer(uint64)
        • minor integer(uint64)
        • op string
        • value integer(uint64)
    • num_procs integer(uint32)

      The number of processors on the system.

      This field is Windows-specific and always zero for Linux containers.

    • storage_stats object

      StorageStats is the disk I/O stats for read/write on Windows.

      This type is Windows-specific and omitted for Linux containers.

      Hide storage_stats attributes Show storage_stats attributes object
      • read_count_normalized integer(uint64)
      • read_size_bytes integer(uint64)
      • write_count_normalized integer(uint64)
      • write_size_bytes integer(uint64)
    • cpu_stats object

      CPU related info of the container

      Hide cpu_stats attributes Show cpu_stats attributes object
      • cpu_usage object

        All CPU stats aggregated since container inception.

        Hide cpu_usage attributes Show cpu_usage attributes object
        • total_usage integer(uint64)

          Total CPU time consumed in nanoseconds (Linux) or 100's of nanoseconds (Windows).

        • percpu_usage array[integer(uint64)]

          Total CPU time (in nanoseconds) consumed per core (Linux).

          This field is Linux-specific when using cgroups v1. It is omitted when using cgroups v2 and Windows containers.

        • usage_in_kernelmode integer(uint64)

          Time (in nanoseconds) spent by tasks of the cgroup in kernel mode (Linux), or time spent (in 100's of nanoseconds) by all container processes in kernel mode (Windows).

          Not populated for Windows containers using Hyper-V isolation.

        • usage_in_usermode integer(uint64)

          Time (in nanoseconds) spent by tasks of the cgroup in user mode (Linux), or time spent (in 100's of nanoseconds) by all container processes in kernel mode (Windows).

          Not populated for Windows containers using Hyper-V isolation.

      • system_cpu_usage integer(uint64)

        System Usage.

        This field is Linux-specific and omitted for Windows containers.

      • online_cpus integer(uint32)

        Number of online CPUs.

        This field is Linux-specific and omitted for Windows containers.

      • throttling_data object

        CPU throttling stats of the container.

        This type is Linux-specific and omitted for Windows containers.

        Hide throttling_data attributes Show throttling_data attributes object
        • periods integer(uint64)

          Number of periods with throttling active.

        • throttled_periods integer(uint64)

          Number of periods when the container hit its throttling limit.

        • throttled_time integer(uint64)

          Aggregated time (in nanoseconds) the container was throttled for.

    • precpu_stats object

      CPU related info of the container

      Hide precpu_stats attributes Show precpu_stats attributes object
      • cpu_usage object

        All CPU stats aggregated since container inception.

        Hide cpu_usage attributes Show cpu_usage attributes object
        • total_usage integer(uint64)

          Total CPU time consumed in nanoseconds (Linux) or 100's of nanoseconds (Windows).

        • percpu_usage array[integer(uint64)]

          Total CPU time (in nanoseconds) consumed per core (Linux).

          This field is Linux-specific when using cgroups v1. It is omitted when using cgroups v2 and Windows containers.

        • usage_in_kernelmode integer(uint64)

          Time (in nanoseconds) spent by tasks of the cgroup in kernel mode (Linux), or time spent (in 100's of nanoseconds) by all container processes in kernel mode (Windows).

          Not populated for Windows containers using Hyper-V isolation.

        • usage_in_usermode integer(uint64)

          Time (in nanoseconds) spent by tasks of the cgroup in user mode (Linux), or time spent (in 100's of nanoseconds) by all container processes in kernel mode (Windows).

          Not populated for Windows containers using Hyper-V isolation.

      • system_cpu_usage integer(uint64)

        System Usage.

        This field is Linux-specific and omitted for Windows containers.

      • online_cpus integer(uint32)

        Number of online CPUs.

        This field is Linux-specific and omitted for Windows containers.

      • throttling_data object

        CPU throttling stats of the container.

        This type is Linux-specific and omitted for Windows containers.

        Hide throttling_data attributes Show throttling_data attributes object
        • periods integer(uint64)

          Number of periods with throttling active.

        • throttled_periods integer(uint64)

          Number of periods when the container hit its throttling limit.

        • throttled_time integer(uint64)

          Aggregated time (in nanoseconds) the container was throttled for.

    • memory_stats object

      Aggregates all memory stats since container inception on Linux. Windows returns stats for commit and private working set only.

      Hide memory_stats attributes Show memory_stats attributes object
      • usage integer(uint64)

        Current res_counter usage for memory.

        This field is Linux-specific and omitted for Windows containers.

      • max_usage integer(uint64)

        Maximum usage ever recorded.

        This field is Linux-specific and only supported on cgroups v1. It is omitted when using cgroups v2 and for Windows containers.

      • stats object

        All the stats exported via memory.stat. when using cgroups v2.

        This field is Linux-specific and omitted for Windows containers.

        Hide stats attribute Show stats attribute object
        • * integer(uint64) Additional properties
      • failcnt integer(uint64)

        Number of times memory usage hits limits.

        This field is Linux-specific and only supported on cgroups v1. It is omitted when using cgroups v2 and for Windows containers.

      • limit integer(uint64)

        This field is Linux-specific and omitted for Windows containers.

      • commitbytes integer(uint64)

        Committed bytes.

        This field is Windows-specific and omitted for Linux containers.

      • commitpeakbytes integer(uint64)

        Peak committed bytes.

        This field is Windows-specific and omitted for Linux containers.

      • privateworkingset integer(uint64)

        Private working set.

        This field is Windows-specific and omitted for Linux containers.

    • networks object

      Network statistics for the container per interface.

      This field is omitted if the container has no networking enabled.

      Hide networks attribute Show networks attribute object
      • * object Additional properties

        Aggregates the network stats of one container

        Hide * attributes Show * attributes object
        • rx_bytes integer(uint64)

          Bytes received. Windows and Linux.

        • rx_packets integer(uint64)

          Packets received. Windows and Linux.

        • rx_errors integer(uint64)

          Received errors. Not used on Windows.

          This field is Linux-specific and always zero for Windows containers.

        • rx_dropped integer(uint64)

          Incoming packets dropped. Windows and Linux.

        • tx_bytes integer(uint64)

          Bytes sent. Windows and Linux.

        • tx_packets integer(uint64)

          Packets sent. Windows and Linux.

        • tx_errors integer(uint64)

          Sent errors. Not used on Windows.

          This field is Linux-specific and always zero for Windows containers.

        • tx_dropped integer(uint64)

          Outgoing packets dropped. Windows and Linux.

        • endpoint_id string

          Endpoint ID. Not used on Linux.

          This field is Windows-specific and omitted for Linux containers.

        • instance_id string

          Instance ID. Not used on Linux.

          This field is Windows-specific and omitted for Linux containers.
  • 404 application/json

    no such container

    Hide response attribute Show response attribute object
    • message string Required

      The error message.
  • 500 application/json

    server error

    Hide response attribute Show response attribute object
    • message string Required

      The error message.
GET /containers/{id}/stats 
curl \
 --request GET 'http://api.example.com/v1.49/containers/{id}/stats'
Response examples (200) 
{
  "name": "boring_wozniak",
  "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
  "read": "2025-01-16T13:55:22.165243637Z",
  "preread": "2025-01-16T13:55:21.160452595Z",
  "pids_stats": {
    "current": 5,
    "limit": 18446744073709551615
  },
  "blkio_stats": {
    "io_time_recursive": null,
    "sectors_recursive": null,
    "io_queue_recursive": null,
    "io_merged_recursive": null,
    "io_serviced_recursive": null,
    "io_wait_time_recursive": null,
    "io_service_time_recursive": null,
    "io_service_bytes_recursive": [
      {
        "op": "read",
        "major": 254,
        "minor": 0,
        "value": 7593984
      },
      {
        "op": "write",
        "major": 254,
        "minor": 0,
        "value": 100
      }
    ]
  },
  "num_procs": 16,
  "storage_stats": {
    "read_count_normalized": 7593984,
    "read_size_bytes": 7593984,
    "write_count_normalized": 7593984,
    "write_size_bytes": 7593984
  },
  "cpu_stats": {
    "cpu_usage": {
      "total_usage": 29912000,
      "percpu_usage": [
        29912000
      ],
      "usage_in_kernelmode": 21994000,
      "usage_in_usermode": 7918000
    },
    "system_cpu_usage": 5,
    "online_cpus": 5,
    "throttling_data": {
      "periods": 0,
      "throttled_periods": 0,
      "throttled_time": 0
    }
  },
  "precpu_stats": {
    "cpu_usage": {
      "total_usage": 29912000,
      "percpu_usage": [
        29912000
      ],
      "usage_in_kernelmode": 21994000,
      "usage_in_usermode": 7918000
    },
    "system_cpu_usage": 5,
    "online_cpus": 5,
    "throttling_data": {
      "periods": 0,
      "throttled_periods": 0,
      "throttled_time": 0
    }
  },
  "memory_stats": {
    "usage": 0,
    "max_usage": 0,
    "stats": {
      "anon": 1572864,
      "file": 7626752,
      "slab": 1180928,
      "sock": 0,
      "shmem": 0,
      "pgscan": 0,
      "pgfault": 2042,
      "pgsteal": 0,
      "anon_thp": 0,
      "pgrefill": 0,
      "file_dirty": 0,
      "pgactivate": 0,
      "pglazyfree": 0,
      "pgmajfault": 45,
      "active_anon": 1572864,
      "active_file": 5115904,
      "file_mapped": 2723840,
      "pglazyfreed": 0,
      "unevictable": 0,
      "kernel_stack": 16384,
      "pgdeactivate": 0,
      "inactive_anon": 0,
      "inactive_file": 2510848,
      "file_writeback": 0,
      "thp_fault_alloc": 1,
      "slab_reclaimable": 725576,
      "slab_unreclaimable": 455352,
      "thp_collapse_alloc": 0,
      "workingset_refault": 0,
      "workingset_activate": 0,
      "workingset_nodereclaim": 0
    },
    "failcnt": 0,
    "limit": 8217579520,
    "commitbytes": 0,
    "commitpeakbytes": 0,
    "privateworkingset": 0
  },
  "networks": {
    "eth0": {
      "rx_bytes": 5338,
      "tx_bytes": 648,
      "rx_errors": 0,
      "tx_errors": 0,
      "rx_dropped": 0,
      "rx_packets": 36,
      "tx_dropped": 0,
      "tx_packets": 8
    },
    "eth5": {
      "rx_bytes": 4641,
      "tx_bytes": 690,
      "rx_errors": 0,
      "tx_errors": 0,
      "rx_dropped": 0,
      "rx_packets": 26,
      "tx_dropped": 0,
      "tx_packets": 9
    }
  }
}
Response examples (404) 
{
  "message": "No such container: c2ada9df5af8"
}
Response examples (404) 
{
  "message": "Something went wrong."
}
Response examples (500) 
{
  "message": "Something went wrong."
}
Response examples (500) 
{
  "message": "Something went wrong."
}