# List tasks


[API catalog](/reference/api/) · [Docker Engine overview](/reference/api/engine/version/v1.57/) · [Product manual](https://docs.docker.com/engine/) · [OpenAPI specification](/reference/api/engine/version/v1.57.yaml)

API version: 1.57





`GET /tasks`



## Connection and access

[API connection and authentication guidance](/reference/api/engine/version/v1.57/#connection)


Server: `/v1.57`

Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement.

```json
null
```

## Example request

Replace placeholders and provide the required credentials or request body.

```console
curl \
  --request GET \
  --unix-socket "${DOCKER_SOCKET:-/var/run/docker.sock}" \
  --header 'Accept: application/json' \
  'http://localhost/v1.57/tasks'
```



## Parameters

### filters

Location: query. Required: no.

A JSON encoded value of the filters (a `map[string][]string`) to
process on the tasks list.

Available filters:

- `desired-state=(running | shutdown | accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>`


```json
{
  "description": "A JSON encoded value of the filters (a `map[string][]string`) to\nprocess on the tasks list.\n\nAvailable filters:\n\n- `desired-state=(running | shutdown | accepted)`\n- `id=\u003ctask id\u003e`\n- `label=key` or `label=\"key=value\"`\n- `name=\u003ctask name\u003e`\n- `node=\u003cnode id or name\u003e`\n- `service=\u003cservice name\u003e`\n",
  "in": "query",
  "name": "filters",
  "pointer": "/paths/~1tasks/get/parameters/0",
  "schema": {
    "type": "string"
  }
}
```

## Request and responses

### Response 200 application/json

no error


Schema:

```json
{
  "example": [
    {
      "CreatedAt": "2016-06-07T21:07:31.171892745Z",
      "DesiredState": "running",
      "ID": "0kzzo1i0y4jz6027t0k7aezc7",
      "NetworksAttachments": [
        {
          "Addresses": [
            "10.255.0.10/16"
          ],
          "Network": {
            "CreatedAt": "2016-06-07T20:31:11.912919752Z",
            "DriverState": {
              "Name": "overlay",
              "Options": {
                "com.docker.network.driver.overlay.vxlanid_list": "256"
              }
            },
            "ID": "4qvuz4ko70xaltuqbt8956gd1",
            "IPAMOptions": {
              "Configs": [
                {
                  "Gateway": "10.255.0.1",
                  "Subnet": "10.255.0.0/16"
                }
              ],
              "Driver": {
                "Name": "default"
              }
            },
            "Spec": {
              "DriverConfiguration": {},
              "IPAMOptions": {
                "Configs": [
                  {
                    "Gateway": "10.255.0.1",
                    "Subnet": "10.255.0.0/16"
                  }
                ],
                "Driver": {}
              },
              "Labels": {
                "com.docker.swarm.internal": "true"
              },
              "Name": "ingress"
            },
            "UpdatedAt": "2016-06-07T21:07:29.955277358Z",
            "Version": {
              "Index": 18
            }
          }
        }
      ],
      "NodeID": "60gvrl6tm78dmak4yl7srz94v",
      "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
      "Slot": 1,
      "Spec": {
        "ContainerSpec": {
          "Image": "redis"
        },
        "Placement": {},
        "Resources": {
          "Limits": {},
          "Reservations": {}
        },
        "RestartPolicy": {
          "Condition": "any",
          "MaxAttempts": 0
        }
      },
      "Status": {
        "ContainerStatus": {
          "ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
          "PID": 677
        },
        "Message": "started",
        "State": "running",
        "Timestamp": "2016-06-07T21:07:31.290032978Z"
      },
      "UpdatedAt": "2016-06-07T21:07:31.376370513Z",
      "Version": {
        "Index": 71
      }
    },
    {
      "CreatedAt": "2016-06-07T21:07:30.019104782Z",
      "DesiredState": "shutdown",
      "ID": "1yljwbmlr8er2waf8orvqpwms",
      "Name": "hopeful_cori",
      "NetworksAttachments": [
        {
          "Addresses": [
            "10.255.0.5/16"
          ],
          "Network": {
            "CreatedAt": "2016-06-07T20:31:11.912919752Z",
            "DriverState": {
              "Name": "overlay",
              "Options": {
                "com.docker.network.driver.overlay.vxlanid_list": "256"
              }
            },
            "ID": "4qvuz4ko70xaltuqbt8956gd1",
            "IPAMOptions": {
              "Configs": [
                {
                  "Gateway": "10.255.0.1",
                  "Subnet": "10.255.0.0/16"
                }
              ],
              "Driver": {
                "Name": "default"
              }
            },
            "Spec": {
              "DriverConfiguration": {},
              "IPAMOptions": {
                "Configs": [
                  {
                    "Gateway": "10.255.0.1",
                    "Subnet": "10.255.0.0/16"
                  }
                ],
                "Driver": {}
              },
              "Labels": {
                "com.docker.swarm.internal": "true"
              },
              "Name": "ingress"
            },
            "UpdatedAt": "2016-06-07T21:07:29.955277358Z",
            "Version": {
              "Index": 18
            }
          }
        }
      ],
      "NodeID": "60gvrl6tm78dmak4yl7srz94v",
      "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
      "Slot": 1,
      "Spec": {
        "ContainerSpec": {
          "Image": "redis"
        },
        "Placement": {},
        "Resources": {
          "Limits": {},
          "Reservations": {}
        },
        "RestartPolicy": {
          "Condition": "any",
          "MaxAttempts": 0
        }
      },
      "Status": {
        "ContainerStatus": {
          "ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
        },
        "Message": "shutdown",
        "State": "shutdown",
        "Timestamp": "2016-06-07T21:07:30.202183143Z"
      },
      "UpdatedAt": "2016-06-07T21:07:30.231958098Z",
      "Version": {
        "Index": 30
      }
    }
  ],
  "items": {
    "$ref": "#/components/schemas/Task"
  },
  "type": "array"
}
```









Schema example:
```json
[
  {
    "CreatedAt": "2016-06-07T21:07:31.171892745Z",
    "DesiredState": "running",
    "ID": "0kzzo1i0y4jz6027t0k7aezc7",
    "NetworksAttachments": [
      {
        "Addresses": [
          "10.255.0.10/16"
        ],
        "Network": {
          "CreatedAt": "2016-06-07T20:31:11.912919752Z",
          "DriverState": {
            "Name": "overlay",
            "Options": {
              "com.docker.network.driver.overlay.vxlanid_list": "256"
            }
          },
          "ID": "4qvuz4ko70xaltuqbt8956gd1",
          "IPAMOptions": {
            "Configs": [
              {
                "Gateway": "10.255.0.1",
                "Subnet": "10.255.0.0/16"
              }
            ],
            "Driver": {
              "Name": "default"
            }
          },
          "Spec": {
            "DriverConfiguration": {},
            "IPAMOptions": {
              "Configs": [
                {
                  "Gateway": "10.255.0.1",
                  "Subnet": "10.255.0.0/16"
                }
              ],
              "Driver": {}
            },
            "Labels": {
              "com.docker.swarm.internal": "true"
            },
            "Name": "ingress"
          },
          "UpdatedAt": "2016-06-07T21:07:29.955277358Z",
          "Version": {
            "Index": 18
          }
        }
      }
    ],
    "NodeID": "60gvrl6tm78dmak4yl7srz94v",
    "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
    "Slot": 1,
    "Spec": {
      "ContainerSpec": {
        "Image": "redis"
      },
      "Placement": {},
      "Resources": {
        "Limits": {},
        "Reservations": {}
      },
      "RestartPolicy": {
        "Condition": "any",
        "MaxAttempts": 0
      }
    },
    "Status": {
      "ContainerStatus": {
        "ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
        "PID": 677
      },
      "Message": "started",
      "State": "running",
      "Timestamp": "2016-06-07T21:07:31.290032978Z"
    },
    "UpdatedAt": "2016-06-07T21:07:31.376370513Z",
    "Version": {
      "Index": 71
    }
  },
  {
    "CreatedAt": "2016-06-07T21:07:30.019104782Z",
    "DesiredState": "shutdown",
    "ID": "1yljwbmlr8er2waf8orvqpwms",
    "Name": "hopeful_cori",
    "NetworksAttachments": [
      {
        "Addresses": [
          "10.255.0.5/16"
        ],
        "Network": {
          "CreatedAt": "2016-06-07T20:31:11.912919752Z",
          "DriverState": {
            "Name": "overlay",
            "Options": {
              "com.docker.network.driver.overlay.vxlanid_list": "256"
            }
          },
          "ID": "4qvuz4ko70xaltuqbt8956gd1",
          "IPAMOptions": {
            "Configs": [
              {
                "Gateway": "10.255.0.1",
                "Subnet": "10.255.0.0/16"
              }
            ],
            "Driver": {
              "Name": "default"
            }
          },
          "Spec": {
            "DriverConfiguration": {},
            "IPAMOptions": {
              "Configs": [
                {
                  "Gateway": "10.255.0.1",
                  "Subnet": "10.255.0.0/16"
                }
              ],
              "Driver": {}
            },
            "Labels": {
              "com.docker.swarm.internal": "true"
            },
            "Name": "ingress"
          },
          "UpdatedAt": "2016-06-07T21:07:29.955277358Z",
          "Version": {
            "Index": 18
          }
        }
      }
    ],
    "NodeID": "60gvrl6tm78dmak4yl7srz94v",
    "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
    "Slot": 1,
    "Spec": {
      "ContainerSpec": {
        "Image": "redis"
      },
      "Placement": {},
      "Resources": {
        "Limits": {},
        "Reservations": {}
      },
      "RestartPolicy": {
        "Condition": "any",
        "MaxAttempts": 0
      }
    },
    "Status": {
      "ContainerStatus": {
        "ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
      },
      "Message": "shutdown",
      "State": "shutdown",
      "Timestamp": "2016-06-07T21:07:30.202183143Z"
    },
    "UpdatedAt": "2016-06-07T21:07:30.231958098Z",
    "Version": {
      "Index": 30
    }
  }
]
```


### Response 500 application/json

server error


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


### Response 503 application/json

node is not part of a swarm


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


## Complete operation contract

```json
{
  "operationId": "TaskList",
  "parameters": [
    {
      "description": "A JSON encoded value of the filters (a `map[string][]string`) to\nprocess on the tasks list.\n\nAvailable filters:\n\n- `desired-state=(running | shutdown | accepted)`\n- `id=\u003ctask id\u003e`\n- `label=key` or `label=\"key=value\"`\n- `name=\u003ctask name\u003e`\n- `node=\u003cnode id or name\u003e`\n- `service=\u003cservice name\u003e`\n",
      "in": "query",
      "name": "filters",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "example": [
              {
                "CreatedAt": "2016-06-07T21:07:31.171892745Z",
                "DesiredState": "running",
                "ID": "0kzzo1i0y4jz6027t0k7aezc7",
                "NetworksAttachments": [
                  {
                    "Addresses": [
                      "10.255.0.10/16"
                    ],
                    "Network": {
                      "CreatedAt": "2016-06-07T20:31:11.912919752Z",
                      "DriverState": {
                        "Name": "overlay",
                        "Options": {
                          "com.docker.network.driver.overlay.vxlanid_list": "256"
                        }
                      },
                      "ID": "4qvuz4ko70xaltuqbt8956gd1",
                      "IPAMOptions": {
                        "Configs": [
                          {
                            "Gateway": "10.255.0.1",
                            "Subnet": "10.255.0.0/16"
                          }
                        ],
                        "Driver": {
                          "Name": "default"
                        }
                      },
                      "Spec": {
                        "DriverConfiguration": {},
                        "IPAMOptions": {
                          "Configs": [
                            {
                              "Gateway": "10.255.0.1",
                              "Subnet": "10.255.0.0/16"
                            }
                          ],
                          "Driver": {}
                        },
                        "Labels": {
                          "com.docker.swarm.internal": "true"
                        },
                        "Name": "ingress"
                      },
                      "UpdatedAt": "2016-06-07T21:07:29.955277358Z",
                      "Version": {
                        "Index": 18
                      }
                    }
                  }
                ],
                "NodeID": "60gvrl6tm78dmak4yl7srz94v",
                "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
                "Slot": 1,
                "Spec": {
                  "ContainerSpec": {
                    "Image": "redis"
                  },
                  "Placement": {},
                  "Resources": {
                    "Limits": {},
                    "Reservations": {}
                  },
                  "RestartPolicy": {
                    "Condition": "any",
                    "MaxAttempts": 0
                  }
                },
                "Status": {
                  "ContainerStatus": {
                    "ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
                    "PID": 677
                  },
                  "Message": "started",
                  "State": "running",
                  "Timestamp": "2016-06-07T21:07:31.290032978Z"
                },
                "UpdatedAt": "2016-06-07T21:07:31.376370513Z",
                "Version": {
                  "Index": 71
                }
              },
              {
                "CreatedAt": "2016-06-07T21:07:30.019104782Z",
                "DesiredState": "shutdown",
                "ID": "1yljwbmlr8er2waf8orvqpwms",
                "Name": "hopeful_cori",
                "NetworksAttachments": [
                  {
                    "Addresses": [
                      "10.255.0.5/16"
                    ],
                    "Network": {
                      "CreatedAt": "2016-06-07T20:31:11.912919752Z",
                      "DriverState": {
                        "Name": "overlay",
                        "Options": {
                          "com.docker.network.driver.overlay.vxlanid_list": "256"
                        }
                      },
                      "ID": "4qvuz4ko70xaltuqbt8956gd1",
                      "IPAMOptions": {
                        "Configs": [
                          {
                            "Gateway": "10.255.0.1",
                            "Subnet": "10.255.0.0/16"
                          }
                        ],
                        "Driver": {
                          "Name": "default"
                        }
                      },
                      "Spec": {
                        "DriverConfiguration": {},
                        "IPAMOptions": {
                          "Configs": [
                            {
                              "Gateway": "10.255.0.1",
                              "Subnet": "10.255.0.0/16"
                            }
                          ],
                          "Driver": {}
                        },
                        "Labels": {
                          "com.docker.swarm.internal": "true"
                        },
                        "Name": "ingress"
                      },
                      "UpdatedAt": "2016-06-07T21:07:29.955277358Z",
                      "Version": {
                        "Index": 18
                      }
                    }
                  }
                ],
                "NodeID": "60gvrl6tm78dmak4yl7srz94v",
                "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
                "Slot": 1,
                "Spec": {
                  "ContainerSpec": {
                    "Image": "redis"
                  },
                  "Placement": {},
                  "Resources": {
                    "Limits": {},
                    "Reservations": {}
                  },
                  "RestartPolicy": {
                    "Condition": "any",
                    "MaxAttempts": 0
                  }
                },
                "Status": {
                  "ContainerStatus": {
                    "ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
                  },
                  "Message": "shutdown",
                  "State": "shutdown",
                  "Timestamp": "2016-06-07T21:07:30.202183143Z"
                },
                "UpdatedAt": "2016-06-07T21:07:30.231958098Z",
                "Version": {
                  "Index": 30
                }
              }
            ],
            "items": {
              "$ref": "#/components/schemas/Task"
            },
            "type": "array"
          }
        }
      },
      "description": "no error"
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "server error"
    },
    "503": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "node is not part of a swarm"
    }
  },
  "summary": "List tasks",
  "tags": [
    "Task"
  ]
}
```

## Referenced schemas

- [#/components/schemas/ErrorResponse](/reference/api/engine/version/v1.57/schemas/ErrorResponse/)

- [#/components/schemas/Task](/reference/api/engine/version/v1.57/schemas/Task/)




