DOdocker
Container

List containers

Returns a list of containers. For details on the format, see the inspect endpoint.

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

get/containers/json

Request

Query parameters

allboolean

Return all containers. By default, only running containers are shown.

limitinteger

Return this number of most recently created containers, including non-running ones.

sizeboolean

Return the size of container as fields SizeRw and SizeRootFs.

filtersstring

Filters to process on the container list, encoded as JSON (a map[string][]string). For example, {"status": ["paused"]} will only return paused containers.

Available filters:

  • ancestor=(<image-name>[:<tag>], <image id>, or <image@digest>)
  • before=(<container id> or <container name>)
  • expose=(<port>[/<proto>]|<startport-endport>/[<proto>])
  • exited=<int> containers with exit code of <int>
  • health=(starting|healthy|unhealthy|none)
  • id=<ID> a container's ID
  • isolation=(default|process|hyperv) (Windows daemon only)
  • is-task=(true|false)
  • label=key or label="key=value" of a container label
  • name=<name> a container's name
  • network=(<network id> or <network name>)
  • publish=(<port>[/<proto>]|<startport-endport>/[<proto>])
  • since=(<container id> or <container name>)
  • status=(created|restarting|running|removing|paused|exited|dead)
  • volume=(<volume name> or <mount point destination>)

Response

no error

Idstring

The ID of this container as a 128-bit (64-character) hexadecimal string (32 bytes).

Namesstring[]

The names associated with this container. Most containers have a single name, but when using legacy "links", the container can have multiple names.

For historic reasons, names are prefixed with a forward-slash (/).

Imagestring

The name or ID of the image used to create the container.

This field shows the image reference as was specified when creating the container, which can be in its canonical form (e.g., docker.io/library/ubuntu:latest or docker.io/library/ubuntu@sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782), short form (e.g., ubuntu:latest)), or the ID(-prefix) of the image (e.g., 72297848456d).

The content of this field can be updated at runtime if the image used to create the container is untagged, in which case the field is updated to contain the the image ID (digest) it was resolved to in its canonical, non-truncated form (e.g., sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782).

ImageIDstring

The ID (digest) of the image that this container was created from.

Commandstring

Command to run when starting the container

Createdinteger

Date and time at which the container was created as a Unix timestamp (number of seconds since EPOCH).

SizeRwinteger nullable

The size of files that have been created or changed by this container.

This field is omitted by default, and only set when size is requested in the API request.

SizeRootFsinteger nullable

The total size of all files in the read-only layers from the image that the container uses. These layers can be shared between containers.

This field is omitted by default, and only set when size is requested in the API request.

Labelsobject

User-defined key/value metadata.

State'created' | 'running' | 'paused' | 'restarting' | 'exited' | 'removing' | 'dead'

The state of this container.

Statusstring

Additional human-readable status of this container (e.g. Exit 0)

Example response

[
  {
    "Id": "aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf",
    "Names": [
      "/funny_chatelet"
    ],
    "Image": "docker.io/library/ubuntu:latest",
    "ImageID": "sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782",
    "ImageManifestDescriptor": {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
      "size": 424,
      "annotations": {
        "com.docker.official-images.bashbrew.arch": "amd64",
        "org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
        "org.opencontainers.image.base.name": "scratch",
        "org.opencontainers.image.created": "2025-01-27T00:00:00Z",
        "org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
        "org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
        "org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
        "org.opencontainers.image.version": "24.04"
      },
      "platform": {
        "architecture": "arm",
        "os": "windows",
        "os.version": "10.0.19041.1165",
        "os.features": [
          "win32k"
        ],
        "variant": "v7"
      }
    },
    "Command": "/bin/bash",
    "Ports": [
      {
        "PrivatePort": 8080,
        "PublicPort": 80,
        "Type": "tcp"
      }
    ],
    "Labels": {
      "com.example.vendor": "Acme",
      "com.example.license": "GPL",
      "com.example.version": "1.0"
    },
    "State": "running",
    "Status": "Up 4 days",
    "HostConfig": {
      "NetworkMode": "mynetwork",
      "Annotations": {
        "io.kubernetes.docker.type": "container",
        "io.kubernetes.sandbox.id": "3befe639bed0fd6afdd65fd1fa84506756f59360ec4adc270b0fdac9be22b4d3"
      }
    },
    "Mounts": [
      {
        "Type": "volume",
        "Name": "myvolume",
        "Source": "/var/lib/docker/volumes/myvolume/_data",
        "Destination": "/usr/share/nginx/html/",
        "Driver": "local",
        "Mode": "z",
        "RW": true
      }
    ],
    "Health": {
      "Status": "healthy"
    }
  }
]

Changes

No recorded changes to this operation across all 2 revisions of this API.