CloudConsole

aws ecs list-tasks

Updated 16 November 2026 · How we write and check guides

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.

Terminal running aws ecs list-tasks --cluster prod --service-name orders-api…
A worked example from this page. Copy commands from the text below, not from the image.

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

OptionNotes
--service-nameTasks belonging to a service.
--familyTasks from any revision of a task definition family.
--started-byMatches the value set at run-task; EventBridge-scheduled tasks often use a rule-based value.
--desired-status STOPPEDRecently stopped tasks only.
--container-instanceTasks 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 app → · Download on the App Store

Sources