Did this page help you? Yes No Tell us about it...

DescribeInstanceStatus

Description

Describes the status of an Amazon EC2 instance including any scheduled events for an instance. Instance status has two main components:

System Status reports impaired functionality that stems from issues related to the systems that support an instance, such as such as hardware failures and network connectivity problems. The DescribeInstanceStatus response elements report such problems as impaired reachability..
Instance Status reports impaired functionality that arises from problems internal to the instance. The DescribeInstanceStatus response elements report such problems as impaired reachability.

Instance status provides information about three types of scheduled events for an instance that may require your attention:

Scheduled Reboot: When Amazon EC2 determines that an instance must be rebooted, the instance’s status will return one of two event codes: system-reboot or instance-reboot. System reboot commonly occurs if certain maintenance or upgrade operations require a reboot of the underlying host that supports an instance. Instance reboot commonly occurs if the instance must be rebooted, rather than the underlying host. Rebooting events include a scheduled start and end time.
System Maintenance: When Amazon EC2 determines that an instance requires maintenance that requires power or network impact, the instance's status will return an event code called system-maintenance. System maintenance is either power maintenance or network maintenance. For power maintenance, your instance will be unavailable for a brief period of time and then rebooted. For network maintenance, your instance will experience a brief loss of network connectivity. System maintenance events include a scheduled start and end time. You will also be notified by email if one of your instances is set for system maintenance. The email message indicates when your instance is scheduled for maintenance.
Scheduled Retirement: When Amazon EC2 determines that an instance must be shut down, the instance’s status will return an event code called instance-retirement. Retirement commonly occurs when the underlying host is degraded and must be replaced. Retirement events include a scheduled start and end time. You will also be notified by email if one of your instances is set to retiring. The email message indicates when your instance will be permanently retired.

When your instance is retired, it will either be terminated (if its root device type is the instance-store) or stopped (if its root device type is an EBS volume). Instances stopped due to retirement will not be restarted, but you can do so manually. You can also avoid retirement of EBS-backed instances by manually restarting your instance when its event code is instance-retirement. This ensures that your instance is started on a different underlying host.

DescribeInstanceStatus returns information only for instances in the running state.

You can filter the results to return information only about instances that match criteria you specify. For example, you could get information about instances in a specific Availability Zone. You can specify multiple values for a filter (e.g., more than one Availability Zone). An instance must match at least one of the specified values for it to be included in the results.

You can specify multiple filters (e.g., the instance is in a specific Availability Zone and its status is set to retiring). An instance must match all the filters for it to be included in the results. If there's no match, no special message is returned; the response is simply empty.

You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\.

The following table shows the available filters.

Filter Name	Description
`availability-zone`	Instance's Availability Zone. Type: String
`event.code`	Code identifying the type of event. Type: String Valid Values: `instance-reboot` \| `system-reboot` \| `system-maintenance` \| `instance-retirement`
`event.description`	A description of the event. Type: String
`event.not-after`	The latest end time for the scheduled event. Type: dateType
`event.not-before`	The earliest start time for the scheduled event. Type: dateType
`instance-state-name`	Intended state of the instance, e.g., running Type: String
`instance-state-code`	Code for intended state of the instance, e.g., 16. Type: Integer
`system-status.status`	The instance's system status. Type: String Valid Values: `ok` \| `impaired` \| `initializing` \| `insufficient-data`
`system-status.reachability`	Filters on system status where the name is `reachability`. Type: String Valid Values: `passed` \| `failed` \| `initializing` \| `insufficient-data`
`instance-status.status`	The instance's status. Type: String Valid Values: `ok` \| `impaired` \| `initializing` \| `insufficient-data`
`instance-status.reachability`	Filters on instance status where the name is `reachability`. Type: String Valid Values: `passed` \| `failed` \|`initializing` \| `insufficient-data`

Request Parameters

Name Description Required

Name	Description	Required
`InstanceId`	The list of instance IDs. If not specified, all instances are described. Type: String Default: None	No
`MaxResults`	The maximum number of paginated instance items per response. Type: Integer Default: None	No
`NextToken`	A string specifying the next paginated set of results to return. Type: String Default: None	No

InstanceId

The list of instance IDs. If not specified, all instances are described.

Type: String

Default: None

MaxResults

The maximum number of paginated instance items per response.

Type: Integer

Default: None

NextToken

A string specifying the next paginated set of results to return.

Type: String

Default: None

Response Elements

The elements in the following table are wrapped in a DescribeInstanceStatusResponse structure.

Name Description

Name	Description
`requestId`	The ID of the request. Type: String
`InstanceStatusSet`	A set of InstanceStatusItemType elements that describe the status of each instance.
`NextToken`	A string specifying the next paginated set of results to return. Type: String

requestId

The ID of the request.

Type: String

InstanceStatusSet

A set of InstanceStatusItemType elements that describe the status of each instance.

NextToken

A string specifying the next paginated set of results to return.

Type: String

Examples

Example Request

This example returns instance status descriptions for all instances.

https://ec2.amazonaws.com/?
Action=DescribeInstanceStatus
&Version=2011-10-01
&AuthParams

Example Request

This example returns instance status descriptions for the specified instances.

https://ec2.amazonaws.com/?
Action=DescribeInstanceStatus
&InstanceId.0=i-0cf27c63
&InstanceId.1=i-283f9f47
&Version=2011-10-01
&AuthParams

Example Request

This example returns instance status descriptions for all instances specified by supported DescribeInstanceStatus filters.

https://ec2.amazonaws.com/?
Action=DescribeInstanceStatus
&Filter.0.Name=system-status.reachability
&Filter.0.Value.failed
&Version=2011-10-01
&AuthParams

Example Response

<DescribeInstanceStatusResponse xmlns='http://ec2.amazonaws.com/doc/2012-04-01/'>
    <requestId>3be1508e-c444-4fef-89cc-0b1223c4f02f</requestId>
    <instanceStatusSet>
        <item>
            <instanceId>i-283f9f47</instanceId>
            <availabilityZone>us-east-1d</availabilityZone>
            <instanceState>
                <code>16</code>
                <name>running</name>
            </instanceState>
            <systemStatus>
                <status>ok</status>
                <details>
                    <item>
                        <name>reachability</name>
                        <status>passed</status>
                    </item>
                </details>
            </systemStatus>
            <instanceStatus>
                <status>ok</status>
                <details>
                    <item>
                        <name>reachability</name>
                        <status>passed</status>
                    </item>
                </details>
            </instanceStatus>
            <eventsSet>
                <code>instance-retirement</eventcode>
                <notBefore>2011-12-05T13:00:00+0000</notBefore>
                <notAfter>2011-12-06T13:00:00+000</notAfter>
                <description>
                    The instance is running on degraded hardware 
                  </description>
            </eventsSet>
        </item>
        <item>
            <instanceId>i-d2e36dbd</instanceId>
            <availabilityZone>us-east-1d</availabilityZone>
            <instanceState>
                <code>16</code>
                <name>running</name>
            </instanceState>
            <systemStatus>
                <status>ok</status>
                <details>
                    <item>
                        <name>reachability</name>
                        <status>passed</status>
                    </item>
                </details>
            </systemStatus>
            <instanceStatus>
                <status>ok</status>
                <details>
                    <item>
                        <name>reachability</name>
                        <status>passed</status>
                    </item>
                </details>
            </instanceStatus>
            <eventsSet>
                <code>instance-reboot</eventcode>
                <notBefore>2011-12-05T13:00:00+0000</notBefore>
                <notAfter>2011-12-06T13:00:00+000</notAfter>
                <description>
                    The instance is scheduled for a reboot
                </description>
            </eventsSet>
        </item>
        <item>
            <instanceId>i-9fa454f1</instanceId>
            <availabilityZone>us-east-1c</availabilityZone>
            <instanceState>
                <code>16</code>
                <name>running</name>
            </instanceState>
            <systemStatus>
                <status>ok</status>
                <details>
                    <item>
                        <name>reachability</name>
                        <status>passed</status>
                    </item>
                </details>
            </systemStatus>
            <instanceStatus>
                <status>ok</status>
                <details>
                    <item>
                        <name>reachability</name>
                        <status>passed</status>
                    </item>
                </details>
            </instanceStatus>
        </item>
        <item>
            <instanceId>i-0ed2936e</instanceId>
            <availabilityZone>us-east-1c</availabilityZone>
            <instanceState>
                <code>16</code>
                <name>running</name>
            </instanceState>
            <systemStatus>
                <status>ok</status>
                <details>
                    <item>
                        <name>reachability</name>
                        <status>passed</status>
                    </item>
                </details>
            </systemStatus>
            <instanceStatus>
                <status>insufficient-data</status>
                <details>
                    <item>
                        <name>reachability</name>
                        <status>insufficient-data</status>
                    </item>
                </details>
            </instanceStatus>
         </item>
    </instanceStatusSet>
</DescribeInstanceStatusResponse>

Document Conventions
Terms of Use

Did this page help you? Yes No Tell us about it...