# Amazon ECS task state change events The following scenarios cause task state change events: You call the `StartTask`, `RunTask`, or `StopTask` API operations, either directly or with the AWS Management Console, AWS CLI, or SDKs. Starting or stopping tasks creates new task resources or modifies the state of existing task resources. The Amazon ECS service scheduler starts or stops a task. Starting or stopping tasks creates new task resources or modifies the state of existing task resources. The Amazon ECS container agent calls the `SubmitTaskStateChange` API operation. For EC2, the Amazon ECS container agent monitors the state of your tasks on your container instances. The Amazon ECS container agent reports any state changes. State changes might include changes from `PENDING` to `RUNNING` or from `RUNNING` to `STOPPED`. You force deregistration of the underlying container instance with the `DeregisterContainerInstance` API operation and the `force` flag, either directly or with the AWS Management Console or SDKs. Deregistering a container instance changes the status of the container instance and the connection status of the Amazon ECS container agent. If tasks are running on the container instance, the `force` flag must be set to allow deregistration. This stops all tasks on the instance. The underlying container instance is stopped or terminated. When you stop or terminate a container instance, the tasks that are running on it are transitioned to the `STOPPED` status. A container in the task changes state. The Amazon ECS container agent monitors the state of containers within tasks. For example, if a container that is running within a task stops, this container state change generates an event. A task using the Fargate Spot capacity provider receives a termination notice. When a task is using the `FARGATE_SPOT` capacity provider and is stopped due to a Spot interruption, a task state change event is generated. **Example Task state change event** Task state change events are delivered in the following format. Note the following about the fields: + The health status of the event is not available in the task state change event. If you need the task health status, you can run [describe-tasks](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html). + When your containers use an image hosted with Amazon ECR, the `imageDigest` field is returned. + The values for the `createdAt`, `connectivityAt`, `pullStartedAt`, `startedAt`, `pullStoppedAt`, and `updatedAt` fields are ISO string timestamps. + The `detail-type` value is "ECS Task State Change". + When the event is generated for a stopped task, the `stoppedReason` and `stopCode` fields provide additional information about why the task stopped (for example, "User initiated"). For more information about EventBridge parameters, see [AWS service event metadata](https://docs.aws.amazon.com/eventbridge/latest/ref/events-structure.html) in the *Amazon EventBridge Events Reference*. For information about how to configure an Amazon EventBridge event rule that only captures task events where the task has stopped running because one of its essential containers has terminated, see [Sending Amazon Simple Notification Service alerts for Amazon ECS task stopped events](ecs_cwet2.md) ``` { "version": "0", "id": "105f6bb1-4da6-c630-4965-35383018cbca", "detail-type": "ECS Task State Change", "source": "aws.ecs", "account": "123456789012", "time": "2025-05-06T11:02:34Z", "region": "us-east-1", "resources": [ "arn:aws:ecs:us-east-1:123456789012:task/example-cluster/a1173316d40a45dea9" ], "detail": { "attachments": [ { "id": "fe3a9a46-6a47-40ee-afd9-7952ae90a75a", "type": "eni", "status": "ATTACHED", "details": [ { "name": "subnetId", "value": "subnet-0d0eab1bb38d5ca64" }, { "name": "networkInterfaceId", "value": "eni-0103a2f01bad57d71" }, { "name": "macAddress", "value": "0e:50:d1:c1:77:81" }, { "name": "privateDnsName", "value": "ip-10-0-1-163.ec2.internal" }, { "name": "privateIPv4Address", "value": "10.0.1.163" } ] } ], "attributes": [ { "name": "ecs.cpu-architecture", "value": "x86_64" } ], "availabilityZone": "us-east-1b", "capacityProviderName": "FARGATE", "clusterArn": "arn:aws:ecs:us-east-1:123456789012:cluster/example-cluster", "connectivity": "CONNECTED", "connectivityAt": "2025-05-06T11:02:17.19Z", "containers": [ { "containerArn": "arn:aws:ecs:us-east-1:123456789012:container/example-cluster/a1173316d40a45dea9/a0a99b87-baa8-4bf6-b9f1-a9a95917a635", "lastStatus": "RUNNING", "name": "web", "image": "nginx", "imageDigest": "sha256:c15da6c91de8d2f436196f3a768483ad32c258ed4e1beb3d367a27ed67253e66", "runtimeId": "a1173316d40a45dea9-0265927825", "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example-cluster/a1173316d40a45dea9", "networkInterfaces": [ { "attachmentId": "fe3a9a46-6a47-40ee-afd9-7952ae90a75a", "privateIpv4Address": "10.0.1.163" } ], "cpu": "99", "memory": "100" }, { "containerArn": "arn:aws:ecs:us-east-1:123456789012:container/example-cluster/a1173316d40a45dea9/a2010e2d-ba7c-4135-8b79-e0290ff3cd8c", "lastStatus": "RUNNING", "name": "aws-guardduty-agent-nm40lC", "imageDigest": "sha256:bf9197abdf853607e5fa392b4f97ccdd6ca56dd179be3ce8849e552d96582ac8", "runtimeId": "a1173316d40a45dea9-2098416933", "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example-cluster/a1173316d40a45dea9", "networkInterfaces": [ { "attachmentId": "fe3a9a46-6a47-40ee-afd9-7952ae90a75a", "privateIpv4Address": "10.0.1.163" } ], "cpu": "null" }, { "containerArn": "arn:aws:ecs:us-east-1:123456789012:container/example-cluster/a1173316d40a45dea9/dccf0ca2-d929-471f-a5c3-98006fd4379e", "lastStatus": "RUNNING", "name": "aws-otel-collector", "image": "public.ecr.aws/aws-observability/aws-otel-collector:v0.32.0", "imageDigest": "sha256:7a1b3560655071bcacd66902c20ebe9a69470d5691fe3bd36baace7c2f3c4640", "runtimeId": "a1173316d40a45dea9-4027662657", "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example-cluster/a1173316d40a45dea9", "networkInterfaces": [ { "attachmentId": "fe3a9a46-6a47-40ee-afd9-7952ae90a75a", "privateIpv4Address": "10.0.1.163" } ], "cpu": "0" } ], "cpu": "256", "createdAt": "2025-05-06T11:02:13.877Z", "desiredStatus": "RUNNING", "enableExecuteCommand": false, "ephemeralStorage": { "sizeInGiB": 20 }, "group": "family:webserver", "launchType": "FARGATE", "lastStatus": "RUNNING", "memory": "512", "overrides": { "containerOverrides": [ { "name": "web" }, { "environment": [ { "name": "CLUSTER_NAME", "value": "example-cluster" }, { "name": "REGION", "value": "us-east-1" }, { "name": "HOST_PROC", "value": "/host_proc" }, { "name": "AGENT_RUNTIME_ENVIRONMENT", "value": "ecsfargate" }, { "name": "STAGE", "value": "prod" } ], "memory": 128, "name": "aws-guardduty-agent-nm40lC" }, { "name": "aws-otel-collector" } ] }, "platformVersion": "1.4.0", "pullStartedAt": "2025-05-06T11:02:24.162Z", "pullStoppedAt": "2025-05-06T11:02:33.493Z", "startedAt": "2025-05-06T11:02:34.325Z", "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example-cluster/a1173316d40a45dea9", "taskDefinitionArn": "arn:aws:ecs:us-east-1:123456789012:task-definition/webserver:5", "updatedAt": "2025-05-06T11:02:34.325Z", "version": 3 } } ``` **Example** The following is an example of a task state change event for EC2. ``` { "version": "0", "id": "a65cf262-f104-0dd5-ceda-4b09ba71a441", "detail-type": "ECS Task State Change", "source": "aws.ecs", "account": "123456789012", "time": "2025-05-12T13:12:06Z", "region": "us-east-1", "resources": [ "arn:aws:ecs:us-east-1:123456789012:task/example/c1ffa94f19a540ed8d9f7e1d2a5d" ], "detail": { "attachments": [ { "id": "52333e3b-b812-41a8-b057-9ed184bbe5e1", "type": "eni", "status": "ATTACHED", "details": [ { "name": "subnetId", "value": "subnet-0d0eab1bb38d5ca64" }, { "name": "networkInterfaceId", "value": "eni-0ea90f746500773a4" }, { "name": "macAddress", "value": "0e:d5:9b:ce:49:fb" }, { "name": "privateDnsName", "value": "ip-10-0-1-37.ec2.internal" }, { "name": "privateIPv4Address", "value": "10.0.1.37" } ] } ], "attributes": [ { "name": "ecs.cpu-architecture", "value": "x86_64" } ], "availabilityZone": "us-east-1b", "capacityProviderName": "Infra-ECS-Cluster-example-fa84e0cc-AsgCapacityProvider-OseQJU9pizmp", "clusterArn": "arn:aws:ecs:us-east-1:123456789012:cluster/example", "connectivity": "CONNECTED", "connectivityAt": "2025-05-12T13:11:44.98Z", "containerInstanceArn": "arn:aws:ecs:us-east-1:123456789012:container-instance/example/d1d84798400f49f3b21cb61610c1e", "containers": [ { "containerArn": "arn:aws:ecs:us-east-1:123456789012:container/example/c1ffa94f19a540ed8d9f7e1d2a5d3626/197d0994-5367-4a6d-9f9a-f075e4a6", "lastStatus": "RUNNING", "name": "aws-otel-collector", "image": "public.ecr.aws/aws-observability/aws-otel-collector:v0.32.0", "imageDigest": "sha256:7a1b3560655071bcacd66902c20ebe9a69470d5691fe3bd36baace7c2f3c4640", "runtimeId": "8e926f0ccd8fe2b459926f49584ba6d33a3d9f61398dbabe944ee6a13a8ff3a1", "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example/c1ffa94f19a540ed8d9f7e1d2a5d", "networkInterfaces": [ { "attachmentId": "52333e3b-b812-41a8-b057-9ed184bbe5e1", "privateIpv4Address": "10.0.1.37" } ], "cpu": "0" }, { "containerArn": "arn:aws:ecs:us-east-1:123456789012:container/example/c1ffa94f19a540ed8d9f7e1d2a5d3626/cab39ef0-9c50-459d-844b-b9d51d73d", "lastStatus": "RUNNING", "name": "web", "image": "nginx", "imageDigest": "sha256:c15da6c91de8d2f436196f3a768483ad32c258ed4e1beb3d367a27ed67253e66", "runtimeId": "9f1c73f0094f051541d9e5c2ab1e172d83c4eb5171bcc857c4504b02770ff3b8", "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example/c1ffa94f19a540ed8d9f7e1d2a5d", "networkInterfaces": [ { "attachmentId": "52333e3b-b812-41a8-b057-9ed184bbe5e1", "privateIpv4Address": "10.0.1.37" } ], "cpu": "99", "memory": "100" } ], "cpu": "256", "createdAt": "2025-05-12T13:11:44.98Z", "desiredStatus": "RUNNING", "enableExecuteCommand": false, "group": "family:webserver", "launchType": "EC2", "lastStatus": "RUNNING", "memory": "512", "overrides": { "containerOverrides": [ { "name": "aws-otel-collector" }, { "name": "web" } ] }, "pullStartedAt": "2025-05-12T13:11:59.491Z", "pullStoppedAt": "2025-05-12T13:12:05.896Z", "startedAt": "2025-05-12T13:12:06.053Z", "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/example/c1ffa94f19a540ed8d9f7e1d2a5d", "taskDefinitionArn": "arn:aws:ecs:us-east-1:123456789012:task-definition/webserver", "updatedAt": "2025-05-12T13:12:06.053Z", "version": 4 } } ```