Amazon Elastic Compute Cloud
API Reference (API Version 2013-02-01)
AWS Documentation » Amazon EC2 » API Reference » Actions » DescribeVolumes
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

DescribeVolumes

Description

Describes one or more of your Amazon EBS volumes. For more information about Amazon EBS, see Amazon Elastic Block Store in the Amazon Elastic Compute Cloud User Guide.

Request Parameters

VolumeId.n

One or more volume IDs.

Type: String

Default: Describes all volumes that you own, or only those otherwise specified.

Required: No

Filter.n.Name

The name of a filter. See the Supported Filters section for a list of supported filter names.

Type: String

Default: None

Required: No

Filter.n.Value.m

A value for the filter. See the Supported Filters section for a list of supported values for each filter.

Type: String

Default: None

Required: No

Supported Filters

You can specify filters so that the response includes information for only certain volumes. For example, you can use a filter to specify that you're interested in volumes whose status is available. You can specify multiple values for a filter. The response includes information for a volume only if it matches at least one of the filter values that you specified.

You can specify multiple filters (for example, specify that the volume is available, and has a specific tag. The response includes information for a volume only if it matches all the filters that you specified. If there's no match, no special message is returned, the response is simply empty.

You can use wildcards in a filter value. An asterisk (*) matches zero or more characters, and a question mark (?) 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 are the available filters.

attachment.attach-time

The time stamp when the attachment initiated.

Type: DateTime

attachment.delete-on-termination

Whether the volume is deleted on instance termination.

Type: Boolean

attachment.device

The device name that is exposed to the instance (for example, /dev/sda1).

Type: String

attachment.instance-id

The ID of the instance the volume is attached to.

Type: String

attachment.status

The attachment state.

Type: String

Valid values: attaching | attached | detaching | detached

availability-zone

The Availability Zone in which the volume was created.

Type: String

create-time

The time stamp when the volume was created.

Type: DateTime

size

The size of the volume, in GiB (for example, 20).

Type: String

snapshot-id

The snapshot from which the volume was created.

Type: String

status

The status of the volume.

Type: String

Valid values: creating | available | in-use | deleting | deleted | error

tag-key

The key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter "tag-key=Purpose" and the filter "tag-value=X", you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose is X, see the tag:key filter.

For more information about tags, see Tagging Your Resources in the Amazon Elastic Compute Cloud User Guide.

Type: String

tag-value

The value of a tag assigned to the resource. This filter is independent of the tag-key filter.

Type: String

tag:key

Filters the response based on a specific tag/value combination.

Example: To list just the resources that have been assigned tag Purpose=X, specify:

Filter.1.Name=tag:Purpose

Filter.1.Value.1=X

Example: To list just resources that have been assigned tag Purpose=X OR Purpose=Y, specify:

Filter.1.Name=tag:Purpose

Filter.1.Value.1=X

Filter.1.Value.2=Y

volume-id

The volume ID.

Type: String

volume-type

The Amazon EBS volume type. If the volume is an io1 volume, the response includes the IOPS as well.

Type: String

Valid values: standard | io1

Response Elements

The following elements are returned in a DescribeVolumesResponse element.

requestId

The ID of the request.

Type: xsd:string

volumeSet

A list of volumes. Each volume is wrapped in an item element.

Type: DescribeVolumesSetItemResponseType

Examples

Example Request

This example describes all volumes associated with your account.

https://ec2.amazonaws.com/?Action=DescribeVolumes
&AUTHPARAMS

Example Response

<DescribeVolumesResponse xmlns="http://ec2.amazonaws.com/doc/2013-02-01/">
   <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> 
   <volumeSet>
      <item>
         <volumeId>vol-1a2b3c4d</volumeId>
         <size>80</size>
         <snapshotId/>
         <availabilityZone>us-east-1a</availabilityZone>
         <status>in-use</status>
         <createTime>YYYY-MM-DDTHH:MM:SS.SSSZ</createTime>
         <attachmentSet>
            <item>
               <volumeId>vol-1a2b3c4d</volumeId>
               <instanceId>i-1a2b3c4d</instanceId>
               <device>/dev/sdh</device>
               <status>attached</status>
               <attachTime>YYYY-MM-DDTHH:MM:SS.SSSZ</attachTime>
               <deleteOnTermination>false</deleteOnTermination>
            </item>
         </attachmentSet>
         <volumeType>standard</volumeType>				
      </item>
   </volumeSet>
</DescribeVolumesResponse>

Example Request

https://ec2.amazonaws.com/?Action=DescribeVolumes
&Filter.1.Name=attachment.instance-id
&Filter.1.Value.1=i-1a2b3c4d
&Filter.2.Name=attachment.delete-on-termination
&Filter.2.Value.1=true
&AUTHPARAMS
Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...