/containers/json 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 .
Connection and access
API connection and authentication guidance
/v1.57
No HTTP authentication requirement is declared for this operation. Transport access controls can still apply.
Parameters
all
query
Type:
boolean
All schema constraints and annotations
{
"default": false,
"type": "boolean"
}limit
query
Type:
integer
All schema constraints and annotations
{
"type": "integer"
}size
query
SizeRw and SizeRootFs.Type:
boolean
All schema constraints and annotations
{
"default": false,
"type": "boolean"
}filters
query
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>)annotation=keyorannotation="key=value"of a container annotationbefore=(<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 IDisolation=(default|process|hyperv) (Windows daemon only)is-task=(true|false)label=keyorlabel="key=value"of a container labelname=<name>a container's namenetwork=(<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>)
Type:
string
All schema constraints and annotations
{
"type": "string"
}Request and responses
Response
200
application/json
Type:
array
Array item
Schema:
ContainerSummary
All schema constraints and annotations
{
"items": {
"$ref": "#/components/schemas/ContainerSummary"
},
"type": "array"
}Response
400
application/json
Schema:
ErrorResponse
Schema example
{
"message": "Something went wrong."
}Response
500
application/json
Schema:
ErrorResponse
Schema example
{
"message": "Something went wrong."
}Referenced schemas
#/components/schemas/ContainerSummary
#/components/schemas/ErrorResponse
Complete operation contract
{
"description": "Returns a list of containers. For details on the format, see the\n[inspect endpoint](#operation/ContainerInspect).\n\nNote that it uses a different, smaller representation of a container\nthan inspecting a single container. For example, the list of linked\ncontainers is not propagated .\n",
"operationId": "ContainerList",
"parameters": [
{
"description": "Return all containers. By default, only running containers are shown.\n",
"in": "query",
"name": "all",
"schema": {
"default": false,
"type": "boolean"
}
},
{
"description": "Return this number of most recently created containers, including\nnon-running ones.\n",
"in": "query",
"name": "limit",
"schema": {
"type": "integer"
}
},
{
"description": "Return the size of container as fields `SizeRw` and `SizeRootFs`.\n",
"in": "query",
"name": "size",
"schema": {
"default": false,
"type": "boolean"
}
},
{
"description": "Filters to process on the container list, encoded as JSON (a\n`map[string][]string`). For example, `{\"status\": [\"paused\"]}` will\nonly return paused containers.\n\nAvailable filters:\n\n- `ancestor`=(`\u003cimage-name\u003e[:\u003ctag\u003e]`, `\u003cimage id\u003e`, or `\u003cimage@digest\u003e`)\n- `annotation=key` or `annotation=\"key=value\"` of a container annotation\n- `before`=(`\u003ccontainer id\u003e` or `\u003ccontainer name\u003e`)\n- `expose`=(`\u003cport\u003e[/\u003cproto\u003e]`|`\u003cstartport-endport\u003e/[\u003cproto\u003e]`)\n- `exited=\u003cint\u003e` containers with exit code of `\u003cint\u003e`\n- `health`=(`starting`|`healthy`|`unhealthy`|`none`)\n- `id=\u003cID\u003e` a container's ID\n- `isolation=`(`default`|`process`|`hyperv`) (Windows daemon only)\n- `is-task=`(`true`|`false`)\n- `label=key` or `label=\"key=value\"` of a container label\n- `name=\u003cname\u003e` a container's name\n- `network`=(`\u003cnetwork id\u003e` or `\u003cnetwork name\u003e`)\n- `publish`=(`\u003cport\u003e[/\u003cproto\u003e]`|`\u003cstartport-endport\u003e/[\u003cproto\u003e]`)\n- `since`=(`\u003ccontainer id\u003e` or `\u003ccontainer name\u003e`)\n- `status=`(`created`|`restarting`|`running`|`removing`|`paused`|`exited`|`dead`)\n- `volume`=(`\u003cvolume name\u003e` or `\u003cmount point destination\u003e`)\n",
"in": "query",
"name": "filters",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/ContainerSummary"
},
"type": "array"
}
}
},
"description": "no error"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "bad parameter"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "server error"
}
},
"summary": "List containers",
"tags": [
"Container"
]
}