List containers

/v1.33

GET

/containers/json

Container

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 .

Response Example

200 - response

[
    {
        "Command": "echo 1",
        "Created": 1367854155,
        "HostConfig": {
            "NetworkMode": "default"
        },
        "Id": "8dfafdbc3a40",
        "Image": "ubuntu:latest",
        "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
        "Labels": {
            "com.example.license": "GPL",
            "com.example.vendor": "Acme",
            "com.example.version": "1.0"
        },
        "Mounts": [
            {
                "Destination": "/data",
                "Driver": "local",
                "Mode": "ro,Z",
                "Name": "fac362...80535",
                "Propagation": "",
                "RW": false,
                "Source": "/data"
            }
        ],
        "Names": [
            "/boring_feynman"
        ],
        "NetworkSettings": {
            "Networks": {
                "bridge": {
                    "EndpointID": "2cdc4edb1ded3631c81f57966563e5c8525b81121bb3706a9a9a3ae102711f3f",
                    "Gateway": "172.17.0.1",
                    "GlobalIPv6Address": "",
                    "GlobalIPv6PrefixLen": 0,
                    "IPAddress": "172.17.0.2",
                    "IPPrefixLen": 16,
                    "IPv6Gateway": "",
                    "MacAddress": "02:42:ac:11:00:02",
                    "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812"
                }
            }
        },
        "Ports": [
            {
                "PrivatePort": 2222,
                "PublicPort": 3333,
                "Type": "tcp"
            }
        ],
        "SizeRootFs": 0,
        "SizeRw": 12288,
        "State": "Exited",
        "Status": "Exit 0"
    },
    {
        "Command": "echo 222222",
        "Created": 1367854155,
        "HostConfig": {
            "NetworkMode": "default"
        },
        "Id": "9cd87474be90",
        "Image": "ubuntu:latest",
        "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
        "Labels": {},
        "Mounts": [],
        "Names": [
            "/coolName"
        ],
        "NetworkSettings": {
            "Networks": {
                "bridge": {
                    "EndpointID": "88eaed7b37b38c2a3f0c4bc796494fdf51b270c2d22656412a2ca5d559a64d7a",
                    "Gateway": "172.17.0.1",
                    "GlobalIPv6Address": "",
                    "GlobalIPv6PrefixLen": 0,
                    "IPAddress": "172.17.0.8",
                    "IPPrefixLen": 16,
                    "IPv6Gateway": "",
                    "MacAddress": "02:42:ac:11:00:08",
                    "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812"
                }
            }
        },
        "Ports": [],
        "SizeRootFs": 0,
        "SizeRw": 12288,
        "State": "Exited",
        "Status": "Exit 0"
    },
    {
        "Command": "echo 3333333333333333",
        "Created": 1367854154,
        "HostConfig": {
            "NetworkMode": "default"
        },
        "Id": "3176a2479c92",
        "Image": "ubuntu:latest",
        "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
        "Labels": {},
        "Mounts": [],
        "Names": [
            "/sleepy_dog"
        ],
        "NetworkSettings": {
            "Networks": {
                "bridge": {
                    "EndpointID": "8b27c041c30326d59cd6e6f510d4f8d1d570a228466f956edf7815508f78e30d",
                    "Gateway": "172.17.0.1",
                    "GlobalIPv6Address": "",
                    "GlobalIPv6PrefixLen": 0,
                    "IPAddress": "172.17.0.6",
                    "IPPrefixLen": 16,
                    "IPv6Gateway": "",
                    "MacAddress": "02:42:ac:11:00:06",
                    "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812"
                }
            }
        },
        "Ports": [],
        "SizeRootFs": 0,
        "SizeRw": 12288,
        "State": "Exited",
        "Status": "Exit 0"
    },
    {
        "Command": "echo 444444444444444444444444444444444",
        "Created": 1367854152,
        "HostConfig": {
            "NetworkMode": "default"
        },
        "Id": "4cb07b47f9fb",
        "Image": "ubuntu:latest",
        "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
        "Labels": {},
        "Mounts": [],
        "Names": [
            "/running_cat"
        ],
        "NetworkSettings": {
            "Networks": {
                "bridge": {
                    "EndpointID": "d91c7b2f0644403d7ef3095985ea0e2370325cd2332ff3a3225c4247328e66e9",
                    "Gateway": "172.17.0.1",
                    "GlobalIPv6Address": "",
                    "GlobalIPv6PrefixLen": 0,
                    "IPAddress": "172.17.0.5",
                    "IPPrefixLen": 16,
                    "IPv6Gateway": "",
                    "MacAddress": "02:42:ac:11:00:05",
                    "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812"
                }
            }
        },
        "Ports": [],
        "SizeRootFs": 0,
        "SizeRw": 12288,
        "State": "Exited",
        "Status": "Exit 0"
    }
]

Request

Query Params

all

string

optional

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

limit

integer

optional

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

size

string

optional

Return the size of container as fields SizeRw and SizeRootFs.

filters

string

optional

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>)

volume=(<volume name> or <mount point destination>)

Responses

🟢200no error

application/json

Body

array of:

Command

string

optional

Command to run when starting the container

Created

integer <int64>

optional

When the container was created

HostConfig

object

optional

NetworkMode

string

optional

string

optional

The ID of this container

Image

string

optional

The name of the image used when creating this container

ImageID

string

optional

The ID of the image that this container was created from

Labels

object

optional

User-defined key/value metadata.

Additional properties

string

optional

Mounts

array[object (Mount) {8}]

optional

BindOptions

object

optional

Optional configuration for the bind type.

Consistency

string

optional

The consistency requirement for the mount: default, consistent, cached, or delegated.

ReadOnly

boolean

optional

Whether the mount should be read-only.

Source

string

optional

Mount source (e.g. a volume name, a host path).

Target

string

optional

Container path.

TmpfsOptions

object

optional

Optional configuration for the tmpfs type.

Type

enum<string>

optional

The mount type. Available types:

bind Mounts a file or directory from the host into the container. Must exist prior to creating the container.

volume Creates a volume with the given name and options (or uses a pre-existing volume with the same name and options). These are not removed when the container is removed.

tmpfs Create a tmpfs with the given options. The mount source cannot be specified for tmpfs.

Allowed values:

bindvolumetmpfs

VolumeOptions

object

optional

Optional configuration for the volume type.

Names

array[string]

optional

The names that this container has been given

NetworkSettings

object

optional

A summary of the container's network settings

Networks

object

optional

Ports

array[object (Port) {4}]

optional

The ports exposed by this container

string <ip-address>

optional

PrivatePort

integer

required

Port on the container

PublicPort

integer

optional

Port exposed on the host

Type

enum<string>

required

Allowed values:

tcpudp

SizeRootFs

integer <int64>

optional

The total size of all the files in this container

SizeRw

integer <int64>

optional

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

State

string

optional

The state of this container (e.g. Exited)

Status

string

optional

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

🟠400bad parameter

🔴500server error

Modified at 2022-09-10 17:56:06

Create a container

Delete stopped containers