DescribeVolumes

Description

Describes your Amazon EBS volumes. For more information about Amazon EBS, go to Using Amazon Elastic Block Store in the Amazon Elastic Compute Cloud User Guide.

You can filter the results to return information only about volumes that match criteria you specify. For example, you could get information about volumes whose status is available. You can specify multiple values for a filter (e.g., the volume's status is either available or in-use). A volume 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 volume's status is available, and it is tagged with a particular value). The result includes information for a particular volume only if it matches all your filters. 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
`attachment.attach-time`	Time stamp when the attachment initiated. Type: xsd:dateTime
`attachment.delete-on-termination`	Whether the volume will be deleted on instance termination. Type: Boolean
`attachment.device`	How the volume is exposed to the instance (e.g., /dev/sda1). Type: String
`attachment.instance-id`	ID of the instance the volume is attached to. Type: String
`attachment.status`	Attachment state. Type: String Valid Values: `attaching` \| `attached` \| `detaching` \| `detached`
`availability-zone`	Availability Zone in which the volume was created. Type: String
`create-time`	Time stamp when the volume was created. Type: xsd:dateTime
`size`	Size of the volume, in GiB (e.g., `20`). Type: String
`snapshot-id`	Snapshot from which the volume was created. Type: String
`status`	Status of the volume. Type: String Valid Values: `creating` \| `available` \| `in-use` \| `deleting` \| `deleted` \| `error`
`tag-key`	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=X, see the `tag:key` filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String
`tag-value`	Value of a tag assigned to the resource. This filter is independent of the `tag-key` filter. Type: String
`tag:``key`	Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: `Filter.1.Name=tag:Purpose` `Filter.1.Value.1=X` Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: `Filter.1.Name=tag:Purpose` `Filter.1.Value.1=X` `Filter.1.Value.2=Y`
`volume-id`	Volume ID. Type: String

Request Parameters

Name Description Required

Name	Description	Required
`VolumeId.n`	One or more volume IDs. Type: String Default: Describes all volumes that you own, or only those otherwise specified.	No
`Filter.n.Name`	Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None	No
`Filter.n.Value.m`	A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None	No

VolumeId.n

One or more volume IDs.

Type: String

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

No

Filter.n.Name

Name of a filter. See the preceding table for a list of allowed filter names.

Type: String

Default: None

No

Filter.n.Value.m

A value for the filter. See the preceding table for a list of allowed values for each filter.

Type: String

Default: None

No

Response Elements

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

Name Description

Name	Description
`requestId`	The ID of the request. Type: xsd:string
`volumeSet`	A list of volumes. Each volume's information is wrapped in an `item` element. Type: DescribeVolumesSetItemResponseType

requestId

The ID of the request.

Type: xsd:string

volumeSet

A list of volumes. Each volume's information 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/2011-01-01/">
   <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> 
   <volumeSet>
      <item>
         <volumeId>vol-4282672b</volumeId>
         <size>80</size>
         <snapshotId/>
         <availabilityZone>us-east-1a</availabilityZone>
         <status>in-use</status>
         <createTime>2008-05-07T11:51:50.000Z</createTime>
         <attachmentSet>
            <item>
               <volumeId>vol-4282672b</volumeId>
               <instanceId>i-6058a509</instanceId>
               <device>/dev/sdh</device>
               <status>attached</status>
               <attachTime>2008-05-07T12:51:50.000Z</attachTime>
               <deleteOnTermination>false</deleteOnTermination>
            </item>
         </attachmentSet>
         <tagSet/>				
      </item>
   </volumeSet>
</DescribeVolumesResponse>

Example Request

This example describes all volumes that are both attached to instance i-1a2b3c4d and also set to delete when the instance terminates.

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

DescribeVolumes

Description

Request Parameters

Response Elements

Examples

Example Request

Example Response

Example Request

Related Operations