# aws ecs list-tasks

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws ecs list-tasks --cluster my-cluster --service-name my-service returns the ARNs of that service's running tasks. Add --desired-status STOPPED to list recently stopped tasks, which is the first step in finding out why tasks keep dying; then pass the ARNs to describe-tasks.

## What the command does

`list-tasks` returns task ARNs, filtered by service, task definition family, container instance, the `startedBy` value or launch type. By default it lists tasks whose desired status is `RUNNING`, which includes tasks still starting. It returns no details; use `describe-tasks` for those.

## Syntax

```
aws ecs list-tasks --cluster my-cluster \
  [--service-name my-service | --family my-family | --started-by my-job] \
  [--desired-status RUNNING|PENDING|STOPPED] \
  [--launch-type FARGATE|EC2] \
  [--container-instance <id>]
```

`--service-name` and `--family` cannot be combined.

## Worked examples

**Running tasks of a service, IDs only**:

```
aws ecs list-tasks --cluster prod --service-name orders-api \
  --query "taskArns[]" --output text | tr '\t' '\n' | awk -F/ '{print $NF}'
```

**Recently stopped tasks with their reasons**:

```
STOPPED=$(aws ecs list-tasks --cluster prod --service-name orders-api \
  --desired-status STOPPED --query "taskArns[]" --output text)
[ -n "$STOPPED" ] && aws ecs describe-tasks --cluster prod --tasks $STOPPED \
  --query "tasks[].[taskArn,stopCode,stoppedReason]" --output text
```

**Pick one running task for ECS Exec**:

```
TASK=$(aws ecs list-tasks --cluster prod --service-name orders-api \
  --query "taskArns[0]" --output text)
aws ecs execute-command --cluster prod --task "$TASK" --container web \
  --interactive --command "/bin/sh"
```

**Tasks started by a scheduled job**, if it sets `startedBy`:

```
aws ecs list-tasks --cluster batch --started-by nightly-report --desired-status STOPPED
```

**Count running tasks in a cluster**:

```
aws ecs list-tasks --cluster prod --query "length(taskArns)" --output json
```

## Spotting a crash loop

A service that keeps replacing tasks shows a pattern in `list-tasks`: the running list is short or keeps changing IDs, while the stopped list grows. Count stopped tasks a few minutes apart:

```
aws ecs list-tasks --cluster prod --service-name orders-api --desired-status STOPPED \
  --query "length(taskArns)" --output json
```

If the number climbs steadily, describe a handful of them and group the reasons. The same `stoppedReason` on every task (an exit code, a failed health check, a secrets error) points to one cause; a mix of reasons usually means the tasks are being killed by something external such as scale-in or Spot interruptions. Comparing `startedAt` and `stoppedAt` also helps: tasks that live for only a few seconds fail at start-up, while ones that survive minutes are more likely failing load balancer health checks.

## Filters

| Option | Notes |
|---|---|
| `--service-name` | Tasks belonging to a service. |
| `--family` | Tasks from any revision of a task definition family. |
| `--started-by` | Matches the value set at `run-task`; EventBridge-scheduled tasks often use a rule-based value. |
| `--desired-status STOPPED` | Recently stopped tasks only. |
| `--container-instance` | Tasks on one EC2 container instance. |

## Gotchas

- **Stopped tasks are short-lived in the API.** They are only listed for a limited time (about an hour), so investigate soon or record task state changes through EventBridge.
- **Empty variable traps.** `describe-tasks --tasks` with nothing after it is a parameter error; guard scripts against an empty list.
- **Desired vs last status.** A task listed as `RUNNING` by desired status may still be `PROVISIONING` or `PENDING`; check `lastStatus`.
- **Cluster defaults to `default`** if omitted.

## Questions

### How do I list stopped ECS tasks?

aws ecs list-tasks --cluster my-cluster --desired-status STOPPED, optionally with --service-name. Then describe them to read stoppedReason.

### How do I list all ECS clusters?

aws ecs list-clusters --query "clusterArns[]" --output text, repeated with --region for each region you use.

### How do I get an ECS task ID?

Use list-tasks with --service-name and take the last segment of the task ARN.

## When this happens away from your desk

Finding the right task quickly is half the battle when a service is flapping. CloudConsole, a phone app for AWS, is built to show running and stopped tasks with their reasons on a phone.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [AWS CLI Command Reference: ecs list-tasks](https://docs.aws.amazon.com/cli/latest/reference/ecs/list-tasks.html)
- [ListTasks API reference](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ListTasks.html)

## Related

- [aws ecs describe-tasks](https://cloudconsole.dev/cli/ecs-describe-tasks)
- [aws ecs execute-command](https://cloudconsole.dev/cli/ecs-execute-command)
- [aws ecs list-services](https://cloudconsole.dev/cli/ecs-list-services)
- [aws ecs stop-task](https://cloudconsole.dev/cli/ecs-stop-task)
- [How to exec into an ECS container](https://cloudconsole.dev/how-to/ecs-exec-into-container)
- [aws ecs describe-services](https://cloudconsole.dev/cli/ecs-describe-services)

---

Source: https://cloudconsole.dev/cli/ecs-list-tasks

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
