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

DescribeImages

Description

Returns information about AMIs, AKIs, and ARIs. Images available to you include public images, private images that you own, and private images owned by other AWS accounts but for which you have explicit launch permissions.

Launch permissions fall into three categories:

Launch Permission	Description
public	The owner of the AMI granted launch permissions for the AMI to the `all` group. All AWS accounts have launch permissions for these AMIs.
explicit	The owner of the AMI granted launch permissions to a specific AWS account.
implicit	An AWS account has implicit launch permissions for all the AMIs it owns.

The list of AMIs returned can be modified by specifying AMI IDs, AMI owners, or AWS accounts with launch permissions. If no options are specified, Amazon EC2 returns all AMIs for which you have launch permissions.

If you specify one or more AMI IDs, only AMIs that have the specified IDs are returned. If you specify an invalid AMI ID, an error is returned. If you specify an AMI ID for which you do not have access, it will not be included in the returned results.

If you specify one or more AMI owners, only AMIs from the specified owners and for which you have access are returned. The results can include the account IDs of the specified owners, amazon for AMIs owned by Amazon, or self for AMIs that you own.

If you specify a list of executable users, only AMIs with launch permissions for those users are returned. You can specify account IDs (if you own the AMI(s)), self for AMIs for which you own or have explicit permissions, or all for public AMIs.

	Note
	Deregistered images are included in the returned results for an unspecified interval after deregistration.

You can filter the results to return information only about images that match criteria you specify. For example, you could get information only about images that use a certain kernel. You can specify multiple values for a filter (e.g., the image uses either kernel aki-1a2b3c4d or kernel aki-9b8c7d6f). An image 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 image uses a certain kernel, and uses an Amazon EBS volume as the root device). The result includes information for a particular image 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
`architecture`	Image architecture. Type: String Valid Values: `i386` \| `x86_64`
`block-device-mapping.delete-on-termination`	Whether the Amazon EBS volume is deleted on instance termination. Type: Boolean
`block-device-mapping.device-name`	Device name (e.g., /dev/sdh) for an Amazon EBS volume mapped to the image. Type: String
`block-device-mapping.snapshot-id`	Snapshot ID for an Amazon EBS volume mapped to the image. Type: String
`block-device-mapping.volume-size`	Volume size for an Amazon EBS volume mapped to the image. Type: Integer
`description`	Description of the AMI (provided during image creation). Type: String
`image-id`	ID of the image. Type: String
`image-type`	Type of image. Type: String Valid Values: `machine` \| `kernel` \| `ramdisk`
`is-public`	Whether the image is public. Type: Boolean
`kernel-id`	Kernel ID. Type: String
`manifest-location`	Location of the image manifest. Type: String
`name`	Name of the AMI (provided during image creation). Type: String
`owner-alias`	AWS account alias (e.g., `amazon`) Type: String
`owner-id`	AWS account ID of the image owner. Type: String
`platform`	Use `windows` if you have Windows based AMIs; otherwise leave blank. Type: String Valid Value: `windows`
`product-code`	Product code associated with the AMI. Type: String
`ramdisk-id`	RAM disk ID. Type: String
`root-device-name`	Root device name of the AMI (e.g., /dev/sda1). Type: String
`root-device-type`	Root device type the AMI uses. Type: String Valid Values: `ebs` \| `instance-store`
`state`	State of the image. Type: String Valid Values: `available` \| `pending` \| `failed`
`state-reason-code`	Reason code for the state change. Type: String
`state-reason-message`	Message for the state change. Type: String
`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`
`virtualization-type`	Virtualization type of the image. Type: String Valid Values: `paravirtual` \| `hvm`
`hypervisor`	Hypervisor type of the image. Type: String Valid Values: `ovm` \| `xen`

Request Parameters

Name	Description	Required
`ExecutableBy.n`	Returns AMIs for which the specified user ID has explicit launch permissions. The user ID can be an AWS account ID, `self` to return AMIs for which the sender of the request has explicit launch permissions, or `all` to return AMIs with public launch permissions. Type: String Default: None	No
`ImageId.n`	One or more AMI IDs. Type: String Default: Returns all AMIs, or only those otherwise specified.	No
`Owner.n`	Returns AMIs owned by the specified owner. Multiple owner values can be specified. The IDs `amazon` and `self` can be used to include AMIs owned by Amazon or AMIs owned by you, respectively. Type: String Default: None	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 DescribeImagesResponse structure.

Name Description

Name	Description
`requestId`	The ID of the request. Type: xsd:string
`imagesSet`	A list of images. Each image's information is wrapped in an `item` element. Type: DescribeImagesResponseItemType

requestId

The ID of the request.

Type: xsd:string

imagesSet

A list of images. Each image's information is wrapped in an item element.

Type: DescribeImagesResponseItemType

Examples

Example Request

This example describes the ami-be3adfd7 AMI.

https://ec2.amazonaws.com/?Action=DescribeImages
&ImageId.1=ami-be3adfd7
&AUTHPARAMS

Example Response

<DescribeImagesResponse xmlns="http://ec2.amazonaws.com/doc/2011-12-15/">
  <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> 
  <imagesSet>
    <item>
      <imageId>ami-be3adfd7</imageId>
      <imageLocation>amazon/getting-started</imageLocation>
      <imageState>available</imageState>
      <imageOwnerId>206029621532</imageOwnerId>
      <isPublic>true</isPublic>
      <architecture>i386</architecture>
      <imageType>machine</imageType>
      <kernelId>aki-d3376696</kernelId>
      <ramdiskId>ari-e73766a2</ramdiskId>
      <imageOwnerAlias>amazon</imageOwnerAlias>
      <name>getting-started</name>
      <description>Fedora 8 v1.11 i386 lvm-rootVG-rootFS ext3 ec2pnp enabled</description>
      <rootDeviceType>ebs</rootDeviceType>
      <rootDeviceName>/dev/sda</rootDeviceName>
      <blockDeviceMapping>
        <item>
          <deviceName>/dev/sda</deviceName>
          <ebs>
            <snapshotId>snap-32885f5a</snapshotId>
            <volumeSize>15</volumeSize>
            <deleteOnTermination>false</deleteOnTermination>
          </ebs>
        </item>
      </blockDeviceMapping>
      <virtualizationType>paravirtual</virtualizationType>
      <tagSet/>
      <hypervisor>xen</hypervisor>
    </item>
  </imagesSet>
</DescribeImagesResponse>

Example Request

This example filters the results to display only the public Windows images with an x86_64 architecture.

https://ec2.amazonaws.com/?Action=DescribeImages
&Filter.1.Name=is-public
&Filter.1.Value.1=true
&Filter.2.Name=architecture
&Filter.2.Value.1=x86_64
&Filter.3.Name=platform
&Filter.3.Value.1=windows
&AUTHPARAMS

Example Response

<DescribeImagesResponse xmlns="http://ec2.amazonaws.com/doc/2011-12-15/">
   <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> 
   <imagesSet>
      <item>
         <imageId>ami-dd20c3b4</imageId>
         <imageLocation>ec2-public-windows-images/Server2003r2-x86_64-Win-v1.07.manifest.xml</imageLocation>
         <imageState>available</imageState>
         <imageOwnerId>206029621532</imageOwnerId>
         <isPublic>true</isPublic>
         <architecture>x86_64</architecture>
         <imageType>machine</imageType>
         <platform>windows</platform>
         <imageOwnerAlias>amazon</imageOwnerAlias>
         <rootDeviceType>instance-store</rootDeviceType>
         <blockDeviceMapping/>
         <virtualizationType>hvm</virtualizationType>
         <tagSet/>
         <hypervisor>xen</hypervisor>
      </item>
      ...
   </imagesSet>
</DescribeImagesResponse>

Document Conventions
Terms of Use

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

DescribeImages

Description

Request Parameters

Response Elements

Examples

Example Request

Example Response

Example Request

Example Response

Related Operations