---
title: "List containers"
method: GET
path: "/containers/json"
tags: ["Container"]
---

# List containers

`GET /containers/json`

Returns a list of containers. For details on the format, see the
[inspect endpoint](#operation/ContainerInspect).

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 .

## Query parameters

- `all` boolean
- `limit` integer
- `size` boolean
- `filters` string

## Response `200`

no error

- ContainerSummary[]
  - `Id` string — The ID of this container as a 128-bit (64-character) hexadecimal string (32 bytes).
  - `Names` string[] — 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 (`/`).
  - `Image` string — 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`).
  - `ImageID` string — The ID (digest) of the image that this container was created from.
  - `ImageManifestDescriptor` OCIDescriptor — A descriptor struct containing digest, media type, and size, as defined in the [OCI Content Descriptors Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md).
    - `mediaType` string — The media type of the object this schema refers to.
    - `digest` string — The digest of the targeted content.
    - `size` integer — The size in bytes of the blob.
    - `urls` string[], nullable — List of URLs from which this object MAY be downloaded.
    - `annotations` object, nullable — Arbitrary metadata relating to the targeted content.
    - `data` string, nullable — Data is an embedding of the targeted content. This is encoded as a base64 string when marshalled to JSON (automatically, by encoding/json). If present, Data can be used directly to avoid fetching the targeted content.
    - `platform` OCIPlatform, nullable — Describes the platform which the image in the manifest runs on, as defined in the [OCI Image Index Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-index.md).
      - `architecture` string — The CPU architecture, for example `amd64` or `ppc64`.
      - `os` string — The operating system, for example `linux` or `windows`.
      - `os.version` string — Optional field specifying the operating system version, for example on Windows `10.0.19041.1165`.
      - `os.features` string[] — Optional field specifying an array of strings, each listing a required OS feature (for example on Windows `win32k`).
      - `variant` string — Optional field specifying a variant of the CPU, for example `v7` to specify ARMv7 when architecture is `arm`.
    - `artifactType` string, nullable — ArtifactType is the IANA media type of this artifact.
  - `Command` string — Command to run when starting the container
  - `Created` integer — Date and time at which the container was created as a Unix timestamp (number of seconds since EPOCH).
  - `Ports` PortSummary[] — Port-mappings for the container.
    - `IP` string, ip-address — Host IP address that the container's port is mapped to
    - `PrivatePort` integer, required — Port on the container
    - `PublicPort` integer — Port exposed on the host
    - `Type` 'tcp' | 'udp' | 'sctp', required
  - `SizeRw` integer, 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.
  - `SizeRootFs` integer, 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.
  - `Labels` object — User-defined key/value metadata.
  - `State` 'created' | 'running' | 'paused' | 'restarting' | 'exited' | 'removing' | 'dead' — The state of this container.
  - `Status` string — Additional human-readable status of this container (e.g. `Exit 0`)
  - `HostConfig` object — Summary of host-specific runtime information of the container. This is a reduced set of information in the container's "HostConfig" as available in the container "inspect" response.
    - `NetworkMode` string — Networking mode (`host`, `none`, `container:<id>`) or name of the primary network the container is using. This field is primarily for backward compatibility. The container can be connected to multiple networks for which information can be found in the `NetworkSettings.Networks` field, which enumerates settings per network.
    - `Annotations` object, nullable — Arbitrary key-value metadata attached to the container.
  - `NetworkSettings` object — Summary of the container's network settings
    - `Networks` object — Summary of network-settings for each network the container is attached to.
  - `Mounts` MountPoint[] — List of mounts used by the container.
    - `Type` 'bind' | 'volume' | 'image' | 'tmpfs' | 'npipe' | 'cluster' — The mount type: - `bind` a mount of a file or directory from the host into the container. - `volume` a docker volume with the given `Name`. - `image` a docker image - `tmpfs` a `tmpfs`. - `npipe` a named pipe from the host into the container. - `cluster` a Swarm cluster volume
    - `Name` string — Name is the name reference to the underlying data defined by `Source` e.g., the volume name.
    - `Source` string — Source location of the mount. For volumes, this contains the storage location of the volume (within `/var/lib/docker/volumes/`). For bind-mounts, and `npipe`, this contains the source (host) part of the bind-mount. For `tmpfs` mount points, this field is empty.
    - `Destination` string — Destination is the path relative to the container root (`/`) where the `Source` is mounted inside the container.
    - `Driver` string — Driver is the volume driver used to create the volume (if it is a volume).
    - `Mode` string — Mode is a comma separated list of options supplied by the user when creating the bind/volume mount. The default is platform-specific (`"z"` on Linux, empty on Windows).
    - `RW` boolean — Whether the mount is mounted writable (read-write).
    - `Propagation` string — Propagation describes how mounts are propagated from the host into the mount point, and vice-versa. Refer to the [Linux kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) for details. This field is not used on Windows.
  - `Health` object — Summary of health status Added in v1.52, before that version all container summary not include Health. After this attribute introduced, it includes containers with no health checks configured, or containers that are not running with none
    - `Status` 'none' | 'starting' | 'healthy' | 'unhealthy' — the health status of the container
    - `FailingStreak` integer — FailingStreak is the number of consecutive failures

## Other responses

- `400` — bad parameter
- `500` — server error

---

[API](https://skmtc.net/docker/apis/docker-engine-api.md) · [All operations](https://skmtc.net/docker/apis/docker-engine-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/docker/docker-engine-api/versions/a181425ed19e/schema)