DescribeImages

Amazon EC2: API Version 2007-01-03

previous page next page

DescribeImages

The DescribeImages operation returns information about AMIs available for use by the user. This includes both public AMIs (those available for any user to launch) and private AMIs (those owned by the user making the request and those owned by other users that the user making the request has explicit launch permissions for).

The list of AMIs returned can be modified via optional lists of AMI IDs, owners or users with launch permissions. If all three optional lists are empty all AMIs the user has launch permissions for are returned. Launch permissions fall into three categories:

Launch Permission	Description
public	The `all` group has launch permissions for the AMI. All users have launch permissions for these AMIs.
explicit	The owner of the AMI granted launch permissions to a specific user. for the AMI.
implicit	A user has implicit launch permissions for all AMIs he or she owns.

If one or more of the lists are specified the result set is the intersection of AMIs matching the criteria of the indivdual lists.

Providing the list of AMI IDs requests information for those AMIs only. If no AMI IDs are provided, information of all relevant AMIs will be returned. If an AMI is specified that does not exist a fault is returned. If an AMI is specified that exists but the user making the request does not have launch permissions for, then that AMI will not be included in the returned results.

Providing the list of owners requests information for AMIs owned by the specified owners only. Only AMIs the user has launch permissions for are returned. The items of the list may be account ids for AMIs owned by users with those account ids, amazon for AMIs owned by Amazon or self for AMIs owned by the user making the request.

The executable list may be provided to request information for AMIs that only the specified users have launch permissions for. The items of the list may be account ids for AMIs owned by the user making the request that the users with the specified account ids have explicit launch permissions for, self for AMIs the user making the request has explicit launch permissions for or all for public AMIs.

Deregistered images will be included in the returned results for an unspecified interval subsequent to deregistration.

Request Parameters

The following table describes the request parameters for DescribeImages. Parameter names are case sensitive.

Element Name	Definition	Required?	Type
`imageSet`	AMI IDs to describe	Yes (but may be empty)	`xsd:string[]`
`ownersSet`	Owners of AMIs to describe	Yes (but may be empty)	`xsd:string[]`
`executableBySet`	Describe AMIs that the specified users have launch permissions for	Yes (but may be empty)	`xsd:string[]`

Response Tags

The following table describes the default response tags included in DescribeImages responses.

Element Name	Definition	Type
`imagesSet`	A list of image descriptions	`ec2:DescribeImagesResponseItemType[]`

Sample Request

<DescribeImages xmlns="http://ec2.amazonaws.com/doc/2007-01-03">
  <executableBySet>
    <item>
      <user>all</user>
    </item>
  </executableBySet>
  <ownersSet />
  <imagesSet>
    <item>
      <imageId>ami-61a54008</imageId>
      <imageId>ami-72f53012</imageId>
    </item>
  </imagesSet>
</DescribeImages>

Sample Response

<DescribeImagesResponse xmlns="http://ec2.amazonaws.com/doc/2007-01-03">
  <imagesSet>
    <item>
      <imageId>ami-61a54008</imageId>
      <imageLocation>aes-ttylinux/image.manifest.xml</imageLocation>
      <imageState>available</imageState>
      <imageOwnerId>UYY3TLBUXIEON5NQVUUX6OMPWBZIQNFM</imageOwnerId>
      <isPublic>true</isPublic>
      <productCodes>
        <item>
          <productCode>774F4FF8</productCode>
        </item>
      </productCodes>
    </item>
  </imagesSet>
</DescribeImagesResponse>

Related Operations

previous page start next page