# aws ecs describe-services

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws ecs describe-services --cluster my-cluster --services my-service returns a service's desired, running and pending task counts, its deployments and their rollout state, its current task definition and the last service events. The events list is where ECS explains why tasks are not starting or not becoming healthy.

## What the command does

Up to ten services can be described per call. Each entry in `services[]` includes `status`, `desiredCount`, `runningCount`, `pendingCount`, `taskDefinition`, `launchType` or `capacityProviderStrategy`, `loadBalancers`, `networkConfiguration`, `deployments[]` and `events[]`, the most recent service scheduler messages, newest first.

Services that do not exist appear under `failures[]` with reason `MISSING` rather than causing an error.

## Syntax

```
aws ecs describe-services --cluster my-cluster --services svc-a [svc-b ...] [--include TAGS]
```

## Worked examples

**Health at a glance**:

```
aws ecs describe-services --cluster prod --services orders-api \
  --query "services[0].[status,desiredCount,runningCount,pendingCount,taskDefinition]" --output text
```

**The last ten events**, the fastest way to see why a service is unhappy:

```
aws ecs describe-services --cluster prod --services orders-api \
  --query "services[0].events[:10].[createdAt,message]" --output text
```

Typical messages: `has reached a steady state`, `was unable to place a task because no container instance met all of its requirements`, `(task ...) failed container health checks`, `is unhealthy in target-group ... due to (reason Health checks failed)`.

**Deployment progress**:

```
aws ecs describe-services --cluster prod --services orders-api \
  --query "services[0].deployments[].{status:status,td:taskDefinition,state:rolloutState,reason:rolloutStateReason,running:runningCount,failed:failedTasks}" \
  --output table
```

**Every service in a cluster that is below its desired count** (describe in batches of ten):

```
for s in $(aws ecs list-services --cluster prod --query "serviceArns[]" --output text); do
  aws ecs describe-services --cluster prod --services "$s" \
    --query "services[?runningCount<desiredCount].[serviceName,runningCount,desiredCount]" --output text
done
```

This makes one call per service, which is fine for a few dozen; for larger clusters, group ARNs into batches of ten per call.

**Which target group and container port the service registers**:

```
aws ecs describe-services --cluster prod --services orders-api \
  --query "services[0].loadBalancers" --output table
```

## Reading the counts

| Pattern | Likely meaning |
|---|---|
| running = desired, one deployment | Steady state. |
| running < desired, pending > 0 | Tasks are starting: pulling images, waiting for ENIs or capacity. |
| running < desired, pending 0, events mention placement | No capacity that fits; see [unable to place a task](https://cloudconsole.dev/errors/ecs-unable-to-place-task). |
| Two deployments for a long time | The new revision is not becoming healthy; tasks are being replaced repeatedly. |
| `failedTasks` rising on the PRIMARY deployment | Tasks crash or fail health checks; read stopped tasks with `describe-tasks`. |

## Gotchas

- **Cluster defaults to `default`** when omitted, so an existing service shows up as `MISSING`.
- **Event history is short.** Only the latest events are kept, and steady-state messages repeat every few hours. Use EventBridge or Container Insights for long-term history.
- **Ten services per call.** More than ten fails with `InvalidParameterException`; batch them.
- **Counts lag slightly** behind reality during fast scaling.
- **Tags are opt-in.** Add `--include TAGS` when you need tags for ownership or cost reports; they are left out by default.

## Questions

### How do I see why an ECS service is not starting tasks?

Read services[0].events from describe-services, then describe recently stopped tasks with list-tasks --desired-status STOPPED and describe-tasks to see stoppedReason.

### How do I describe an ECS cluster?

Use aws ecs describe-clusters --clusters my-cluster, which returns counts of running tasks, active services and registered container instances.

### How do I describe an ECS task definition?

Use aws ecs describe-task-definition --task-definition family:revision. The service's current revision is in services[0].taskDefinition.

## When this happens away from your desk

Service events are the first thing to read when an ECS alarm fires. CloudConsole, a phone app for AWS, is built to put service health, events and logs on one phone screen.

[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 describe-services](https://docs.aws.amazon.com/cli/latest/reference/ecs/describe-services.html)
- [DescribeServices API reference](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeServices.html)

## Related

- [aws ecs update-service](https://cloudconsole.dev/cli/ecs-update-service)
- [aws ecs describe-tasks](https://cloudconsole.dev/cli/ecs-describe-tasks)
- [aws ecs list-services](https://cloudconsole.dev/cli/ecs-list-services)
- [service was unable to place a task because no container instance met all of its requirements](https://cloudconsole.dev/errors/ecs-unable-to-place-task)
- [Task failed ELB health checks in target group](https://cloudconsole.dev/errors/ecs-task-failed-elb-health-checks)
- [aws ecs describe-task-definition](https://cloudconsole.dev/cli/ecs-describe-task-definition)

---

Source: https://cloudconsole.dev/cli/ecs-describe-services

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