AWS Documentation » Amazon EC2 » API Reference » Actions » DescribeImages	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

DescribeImages

Description

Describes the images (AMIs, AKIs, and ARIs) available to you. 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:

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, or marketplace for AMIs from the AWS Marketplace.

Note

For an overview of the AWS Marketplace, see https://aws.amazon.com/marketplace/help/200900000. For details on how to use the AWS Marketplace, see AWS Marketplace.

If you specify a list users with launch permissions, 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.

Request Parameters

ExecutableBy.n

The 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

Required: No

ImageId.n

One or more AMI IDs.

Type: String

Default: Returns all AMIs, or only those otherwise specified.

Required: No

Owner.n

The AMIs owned by the specified owner. Multiple owner values can be specified. The IDs amazon, aws-marketplace, and self can be used to include AMIs owned by Amazon, AWS Marketplace, or AMIs owned by you, respectively.

Type: String

Default: None

Valid values: amazon | aws-marketplace | self | AWS account ID | all

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 images. For example, you can use a filter to specify that you're interested in images that use a specific kernel. You can specify multiple values for a filter. The response includes information for an image only if it matches at least one of the filter values that you specified.

You can specify multiple filters; for example, specify images that use a specific kernel and use an Amazon EBS volume as the root device. The response includes information for an image 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.

architecture

The 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

The device name (for example, /dev/sdh) for the Amazon EBS volume.

Type: String

block-device-mapping.snapshot-id

The ID of the snapshot used for the Amazon EBS volume.

Type: String

block-device-mapping.volume-size

The volume size of the Amazon EBS volume, in GiB.

Type: Integer

block-device-mapping.volume-type

The volume type of the Amazon EBS volume.

Type: String

Valid values: standard | io1

description

The description of the image (provided during image creation).

Type: String

image-id

The ID of the image.

Type: String

image-type

The image type.

Type: String

Valid values: machine | kernel | ramdisk

is-public

Whether the image is public.

Type: Boolean

kernel-id

The kernel ID.

Type: String

manifest-location

The location of the image manifest.

Type: String

name

The name of the AMI (provided during image creation).

Type: String

owner-alias

The AWS account alias (for example, amazon).

Type: String

owner-id

The AWS account ID of the image owner.

Type: String

platform

The platform. To only list Windows-based AMIs, use windows. Otherwise, leave blank.

Type: String

Valid value: windows

product-code

The product code.

Type: String

product-code.type

The type of the product code.

Type: String

Valid values: devpay | marketplace

ramdisk-id

The RAM disk ID.

Type: String

root-device-name

The name of the root device volume (for example, /dev/sda1).

Type: String

root-device-type

The type of the root device volume.

Type: String

Valid values: ebs | instance-store

state

The state of the image.

Type: String

Valid values: available | pending | failed

state-reason-code

The reason code for the state change.

Type: String

state-reason-message

The message for the state change.

Type: String

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

virtualization-type

The virtualization type.

Type: String

Valid values: paravirtual | hvm

hypervisor

The hypervisor type.

Type: String

Valid values: ovm | xen

Response Elements

The following elements are returned in a DescribeImagesResponse element.

requestId

The ID of the request.

Type: xsd:string

imagesSet

A list of images, each one 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/2013-02-01/">
  <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> 
  <imagesSet>
    <item>
      <imageId>ami-1a2b3c4d</imageId>
      <imageLocation>amazon/getting-started</imageLocation>
      <imageState>available</imageState>
      <imageOwnerId>111122223333</imageOwnerId>
      <isPublic>true</isPublic>
      <architecture>i386</architecture>
      <imageType>machine</imageType>
      <kernelId>aki-1a2b3c4d</kernelId>
      <ramdiskId>ari-1a2b3c4d</ramdiskId>
      <imageOwnerAlias>amazon</imageOwnerAlias>
      <name>getting-started</name>
      <description>Image Description</description>
      <rootDeviceType>ebs</rootDeviceType>
      <rootDeviceName>/dev/sda</rootDeviceName>
      <blockDeviceMapping>
        <item>
          <deviceName>/dev/sda1</deviceName>
          <ebs>
            <snapshotId>snap-1a2b3c4d</snapshotId>
            <volumeSize>15</volumeSize>
            <deleteOnTermination>false</deleteOnTermination>
            <volumeType>standard</volumeType>
          </ebs>
        </item>
      </blockDeviceMapping>
      <virtualizationType>paravirtual</virtualizationType>
      <tagSet/>
      <hypervisor>xen</hypervisor>
    </item>
  </imagesSet>
</DescribeImagesResponse>

Example Request

This example filters the response to include 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/2013-02-01/">
   <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> 
   <imagesSet>
      <item>
         <imageId>ami-1a2b3c4d</imageId>
         <imageLocation>ec2-public-windows-images/Server2003r2-x86_64-Win-v1.07.manifest.xml</imageLocation>
         <imageState>available</imageState>
         <imageOwnerId>111122223333></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>

Example Request

This example returns the results to display images where the owner is aws-marketplace.

https://ec2.amazonaws.com/?Action=DescribeImages
&Owner.0=aws-marketplace
&AUTHPARAMS

Example Response

<DescribeImagesResponse xmlns="http://ec2.amazonaws.com/doc/2013-02-01/">
         <requestId>4a4a27a2-2e7c-475d-b35b-ca822EXAMPLE</requestId>
    <imagesSet>
        <item>
            <imageId>ami-1a2b3c4d</imageId>
            <imageLocation>aws-marketplace/example-marketplace-amzn-ami.1</imageLocation>
            <imageState>available</imageState>
            <imageOwnerId>111122223333</imageOwnerId>
            <isPublic>true</isPublic>
            <productCodes>
                <item>
                    <productCode>a1b2c3d4e5f6g7h8i9j10k11</productCode>
                    <type>marketplace</type>
                </item>
            </productCodes>
            <architecture>i386</architecture>
            <imageType>machine</imageType>
            <kernelId>aki-1a2b3c4d</kernelId>
            <imageOwnerAlias>aws-marketplace</imageOwnerAlias>
            <name>example-marketplace-amzn-ami.1</name>
            <description>Amazon Linux AMI i386 EBS</description>
            <rootDeviceType>ebs</rootDeviceType>
            <rootDeviceName>/dev/sda1</rootDeviceName>
            <blockDeviceMapping>
                <item>
                    <deviceName>/dev/sda1</deviceName>
                    <ebs>
                        <snapshotId>snap-1a2b3c4d</snapshotId>
                        <volumeSize>8</volumeSize>
                        <deleteOnTermination>true</deleteOnTermination>
                    </ebs>
                </item>
            </blockDeviceMapping>
            <virtualizationType>paravirtual</virtualizationType>
            <hypervisor>xen</hypervisor>
        </item>
        ...
    </imagesSet>
</DescribeImagesResponse>

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...

DescribeImages

Description

Request Parameters

Supported Filters

Response Elements

Examples

Example Request

Example Response

Example Request

Example Response

Example Request

Example Response

Related Actions