Help Center/ Image Management Service/ API Reference/ IMS APIs/ Image/ Querying Images

Updated on 2026-08-31 GMT+08:00

Querying Images

Function

This API is used to query images using search criteria. Images meeting the criteria will be shown in the list.

Windows images can no longer be queried.

Debugging

You can debug this API in API Explorer.

Authorization

Each account has all of the permissions required to call all APIs, but IAM users must have the required permissions specifically assigned. For details about the required permissions, see Permissions and Supported Actions.

URI

GET /v2/cloudimages

You can append a question mark (?) and ampersands (&) to a URI to define search criteria. For details, see the example request.
If only enterprise project authorization is used, the enterprise_project_id parameter must be specified (for details about this parameter, see Table 1). Otherwise, an error may occur, indicating that you do not have the required permissions.

**Table 1** Parameter description
Parameter	Mandatory	Type	Description
__isregistered	No	String	Definition Whether an image is registered. Constraints The value is true for extended APIs by default. Common users can only query images whose value is true. Range The value can be true or false. true: The image is registered. false: The image is not registered. Default Value true
__imagetype	No	String	Definition Image type. Constraints __imagetype is shared for both the images you shared with other tenants and those you accepted from them. Use the owner field to distinguish the two types of shared images. You can use member_status to filter shared images you accepted. Range Public image: The value is gold. Private image: The value is private. Shared image: The value is shared. KooGallery image: The value is market. Default Value N/A
__whole_image	No	Boolean	Definition Whether an image is a full-ECS image. Constraints N/A Range The value can be true or false. true: a full-ECS image false: not a full-ECS image Default Value N/A
__system__cmkid	No	String	Definition ID of the key used for image encryption. You can obtain the ID from the IMS console or by calling the Querying Images API. Constraints N/A Range N/A Default Value N/A
protected	No	Boolean	Definition Whether an image is protected. A protected image cannot be deleted. Constraints You are advised to set this parameter to true when querying public images. This parameter is optional when querying private images. Range The value can be true or false. true: protected false: unprotected Default Value N/A
visibility	No	String	Definition Whether an image is visible to other tenants. Constraints N/A Range public: public image private: private image shared: shared image Default Value N/A
owner	No	String	Definition Project ID of the tenant that an image belongs to. For details, see Obtaining a Project ID. Constraints N/A Range N/A Default Value N/A
id	No	String	Definition Image ID. You can obtain the value by calling the Viewing Private Image Details API. You can enter multiple image IDs, separated by commas (,). Constraints A maximum of 50 images can be queried at a time. Range N/A Default Value N/A
status	No	String	Definition Image status. Constraints N/A Range queued: The image metadata has already been created, and the image file is ready to be uploaded. saving: The image file is being uploaded to the backend storage. deleted: The image is deleted. killed: An error occurs during image upload. active: The image is available for use. Default Value N/A
name	No	String	Definition Image name. For details about name, see Image Attributes. Constraints Exact matching is used. Range N/A Default Value N/A
flavor_id	No	String	Definition Cloud server flavor ID used to filter available public images. You can obtain the value by calling the Listing Flavor Details and Extended Information API. Constraints You can only specify one flavor ID. You can only specify an ECS flavor ID and cannot specify a BMS flavor ID. To filter public images for a BMS flavor, use the __support_s4l=true filter criterion. s4l indicates board_type of the BMS flavor physical.s4.large. Refer to Common Query Methods for an example call. Range N/A Default Value N/A
container_format	No	String	Definition Container type. Constraints N/A Range The value is fixed at bare, indicating that no container encapsulation is used. Default Value N/A
disk_format	No	String	Definition Image format. Constraints N/A Range Currently, the value can be zvhd2, vhd, zvhd, raw, iso, or qcow2. Default Value The default value is zvhd2 for a non-ISO image.
min_ram	No	Integer	Definition Minimum memory (MB) required for running an image. Constraints N/A Range The value depends on cloud server specifications. Generally, the value is 0. For details, see ECS Specifications. Default Value N/A
min_disk	No	Integer	Definition Minimum disk space (GB) required for running an image. Constraints N/A Range For Linux, the value ranges from 10 GB to 1024 GB. For Windows, the value ranges from 20 GB to 1024 GB. Default Value N/A
__os_bit	No	String	Definition OS bitness. Constraints N/A Range Generally, the value is 32 or 64. 32: 32-bit OS 64: 64-bit OS Default Value N/A
__platform	No	String	Definition Image platform. Constraints N/A Range The value can be Windows, Ubuntu, Red Hat, SUSE, CentOS, Debian, OpenSUSE, Oracle Linux, Fedora, Huawei Cloud EulerOS, CoreOS, or Other. Default Value N/A
marker	No	String	Definition Image from which the query starts. This parameter is used for pagination. Constraints N/A Range The value is an image ID. For details about how to obtain an image ID, see Viewing Private Image Details. Default Value N/A
limit	No	Integer	Definition Number of images to be queried. This parameter is used for pagination. Constraints N/A Range The value is an integer ranging from 1 to 1000. Default Value 1000
sort_key	No	String	Definition Field used for sorting the query results. Constraints N/A Range name: image name container_format: container type disk_format: image format status: image status id: image ID size: This field is unavailable now. created_at: image creation time Default Value created_at
sort_dir	No	String	Definition Whether the query results are sorted in ascending or descending order. Constraints This parameter is used together with the sort_key parameter. Range The value can be asc or desc. asc: ascending order desc: descending order Default Value The default value is desc.
__os_type	No	String	Definition OS type. Constraints N/A Range Linux Windows Other Default Value N/A
tag	No	String	Definition Image tag. Tags can be used as a filter to query images. NOTE: The tag function has been upgraded. For tags in the format of "Key.Value" before the upgrade, query them using "Key=Value". For example, an existing tag is a.b. After the upgrade, query the tag using tag=a=b. Constraints N/A Range N/A Default Value N/A
member_status	No	String	Definition Image sharing status. Constraints To use this parameter, set visibility to shared. Range accepted: Shared images are accepted. rejected: Shared images are rejected. pending: Shared images are to be accepted or rejected. Default Value N/A
__support_kvm	No	String	Definition Whether an image supports KVM. If yes, the value is true. Otherwise, this parameter is not required. Constraints N/A Range N/A Default Value N/A
__support_xen	No	String	Definition Whether an image supports Xen. If yes, the value is true. Otherwise, this parameter is not required. Constraints N/A Range N/A Default Value N/A
__support_largememory	No	String	Definition Whether an image supports large memory. If an image supports large memory, the value is true. Otherwise, this parameter is not required. For details, see OSs Supported by Different Types of ECSs. Constraints N/A Range N/A Default Value N/A
__support_diskintensive	No	String	Definition Whether an image supports intensive storage. If an image supports intensive storage, the value is true. Otherwise, this parameter is not required. Constraints N/A Range N/A Default Value N/A
__support_highperformance	No	String	Definition Whether an image supports high-performance computing. If an image supports high-performance computing, the value is true. Otherwise, this parameter is not required. Constraints N/A Range N/A Default Value N/A
__support_xen_gpu_type	No	String	Definition Whether an image supports GPUs on the Xen platform. Constraints This parameter cannot co-exist with __support_xen or __support_kvm. Range For details, see Table 2. If an image does not support GPUs on the Xen platform, this parameter is not required. Default Value N/A
__support_kvm_gpu_type	No	String	Definition Whether an image supports GPUs on the KVM platform. Constraints This parameter cannot co-exist with __support_xen or __support_kvm. Range For details, see Table 3. If an image does not support GPUs on the KVM platform, this parameter is not required. Default Value N/A
__support_xen_hana	No	String	Definition Whether an image supports HANA on the Xen platform. Constraints This parameter cannot co-exist with __support_xen or __support_kvm. Range If an image supports HANA on the Xen platform, the value is true. Otherwise, this parameter is not required. Default Value N/A
__support_kvm_infiniband	No	String	Definition Whether an image supports InfiniBand NICs on the KVM platform. Constraints This parameter cannot co-exist with __support_xen. Range If an image supports InfiniBand NICs on the KVM platform, the value is true. Otherwise, this parameter is not required. Default Value N/A
virtual_env_type	No	String	Definition Environment where an image is used. Constraints N/A Range FusionCompute: system disk image DataImage: data disk image Ironic: BMS image IsoImage: ISO image Default Value N/A
enterprise_project_id	No	String	Definition Enterprise project that an image belongs to. For more information about enterprise projects, see Enterprise Center. For details about how to obtain an enterprise project ID, see How Do I Obtain an Enterprise Project ID? Constraints If only enterprise project authorization is used, the enterprise_project_id parameter must be specified. Otherwise, an error may occur, indicating that you do not have the required permissions. Range If the value is 0, the images of the default enterprise project will be returned. If the value is a UUID, images of the enterprise project with this UUID will be returned. If the value is all_granted_eps, images of all enterprise projects of the current user will be returned. Default Value N/A
created_at	No	String	Definition Image creation time. Images can be queried by time. The value is in the format of Operator:UTC time. The time format is yyyy-MM-ddThh:mm:ssZ or yyyy-MM-dd hh:mm:ss. For example, to query images created before Oct 28, 2018 10:00:00, set the value of this parameter as follows: created_at=lt:2018-10-28T10:00:00Z Constraints The operators can be: gt: greater than gte: greater than or equal to lt: less than lte: less than or equal to eq: equal to neq: not equal to Range N/A Default Value N/A
updated_at	No	String	Definition Image update time. The value is in UTC format: yyyy-MM-ddTHH:mm:ssZ or yyyy-MM-dd HH:mm:ss. For example, the value can be 2018-10-28T10:00:00Z. Images can be queried by time. The value is in the format of Operator:UTC time. Constraints The operators can be: gt: greater than gte: greater than or equal to lt: less than lte: less than or equal to eq: equal to neq: not equal to Range N/A Default Value N/A
architecture	No	String	Definition Image architecture. Constraints N/A Range x86: x86 architecture arm: Arm architecture Default Value N/A

Request

Request parameters

None

Example Request

Querying public images (the results will be sorted by image name and only one image will be returned)

GET https://{Endpoint}/v2/cloudimages?__imagetype=gold&sort_key=name&limit=1

Common Query Methods

Public images
GET /v2/cloudimages?__imagetype=gold&visibility=public&protected=true
Private images
GET /v2/cloudimages?owner={project_id}
Available shared images
GET /v2/cloudimages?member_status=accepted&visibility=shared&__imagetype=shared
Rejected images
GET /v2/cloudimages?member_status=rejected&visibility=shared&__imagetype=shared
Unaccepted images
GET /v2/cloudimages?member_status=pending&visibility=shared&__imagetype=shared
Public images supported by a BMS flavor
GET /v2/cloudimages?__imagetype=gold&__support_xxx=true&virtual_env_type=Ironic

Response

Response parameters

Parameter	Type	Description
images	Array of objects	Definition Image details. For details, see Table 2. Range N/A
page_info	object	Definition Pagination information. For details, see Table 3. Range N/A

Parameter

Type

Description

images

Array of objects

Definition

Image details. For details, see Table 2.

Range

N/A

page_info

object

Definition

Pagination information. For details, see Table 3.

Range

N/A

**Table 2** Data structure description of the images field
Parameter	Type	Description
file	String	Definition URL for uploading and downloading an image file. Range N/A
owner	String	Definition Project ID of the tenant that an image belongs to. Range N/A
id	String	Definition Image ID. Range N/A
size	Long	Definition Image file size. This is a reserved field. Range N/A
self	String	Definition Image URL. Range N/A
schema	String	Definition Image schema. Range N/A
status	String	Definition Image status. Range queued: indicates that the image metadata has already been created, and it is ready for the image file to upload. saving: indicates that the image file is being uploaded to the backend storage. deleted: indicates that the image has been deleted. killed: indicates that an error occurs on the image uploading. active: indicates that the image is available for use.
tags	Array of strings	Definition Image tags. With tags, you can manage private images in your own way. You can use the image tag API to add different tags to each image and filter images by tag. Range N/A
visibility	String	Definition Whether an image is visible to other tenants. Range private: private image public: public image shared: shared image
name	String	Definition Image name. For details about name, see Image Attributes. Range N/A
checksum	String	Definition Checksum of the image file content. This is a reserved field. Range N/A
protected	Boolean	Definition Whether an image is protected. A protected image cannot be deleted. Range The value can be true or false. true: protected false: unprotected
container_format	String	Definition Container type. Range The value is fixed at bare, indicating that no container encapsulation is used.
min_ram	Integer	Definition Minimum memory (MB) required for running an image. Range The value depends on cloud server specifications. Generally, the value is 0.
max_ram	String	Definition Maximum memory (MB) supported by an image. Range The value depends on cloud server specifications. Generally, this parameter is not specified.
updated_at	String	Definition Image update time. The value is in UTC format. Range N/A
__os_bit	String	Definition OS bitness. Range Generally, the value is 32 or 64.
__os_version	String	Definition OS version. Range N/A
__description	String	Definition Image description. For details about _description, see Image Attributes. Range N/A
disk_format	String	Definition Image format. Range Currently, the value can be zvhd2, vhd, zvhd, raw, iso, or qcow2.
__isregistered	String	Definition Whether an image is registered. Range The value can be true or false.
__platform	String	Definition Image platform. Range The value can be Windows, Ubuntu, Red Hat, SUSE, CentOS, Debian, OpenSUSE, Oracle Linux, Fedora, Huawei Cloud EulerOS, CoreOS, or Other.
__os_type	String	Definition OS type. Range The value can be Linux, Windows, or Other.
min_disk	Integer	Definition Minimum disk space (GB) required for running an image. Range For Linux, the value ranges from 10 GB to 1024 GB. For Windows, the value ranges from 20 GB to 1024 GB.
virtual_env_type	String	Definition Environment where an image is used. Range FusionCompute: cloud server image DataImage: data disk image Ironic: BMS image IsoImage: ISO image
__image_source_type	String	Definition Image backend storage type. Only UDS is supported currently. Range N/A
__imagetype	String	Definition Image type. Range Public image: The value is gold. Private image: The value is private. Shared image: The value is shared. KooGallery image: The value is market.
created_at	String	Definition Image creation time. The value is in UTC format. Range N/A
virtual_size	Integer	Definition Logical size of a virtual disk. This is a reserved field. Range N/A
__originalimagename	String	Definition Parent image ID. For a public image or an image created from an image file, the value is left blank. Range N/A
__backup_id	String	Definition Backup ID. To create an image using a backup, set the value to the backup ID. Otherwise, this value is left empty. Range N/A
__productcode	String	Definition Product ID of a KooGallery image. Range N/A
__image_size	String	Definition Image file size, in bytes. Range N/A
__data_origin	String	Definition Image source. For a public image, the value is left blank. Range N/A
__lazyloading	String	Definition Whether an image supports lazy loading. Range true: Lazy loading is supported. false: Lazy loading is not supported. True: Lazy loading is supported. False: Lazy loading is not supported.
active_at	String	Definition Time when the image status became active. The value is in UTC format: yyyy-MM-ddTHH:mm:ssZ. Example: 2025-10-28T10:00:00Z Range N/A
__image_displayname	String	Definition Image display name. Range N/A
__os_feature_list	String	Definition Additional image attributes. The value is a list (in JSON format) of advanced features supported by the image. Range N/A
__support_kvm	String	Definition Whether an image supports KVM. Range If an image supports KVM, the value is true. Otherwise, this parameter is not required.
__support_xen	String	Definition Whether an image supports Xen. Range If an image supports Xen, the value is true. Otherwise, this parameter is not required.
__support_largememory	String	Definition Whether an image supports large memory. Range If an image supports large memory, the value is true. Otherwise, this parameter is not required.
__support_diskintensive	String	Definition Whether an image supports intensive storage. Range If an image supports intensive storage, the value is true. Otherwise, this parameter is not required.
__support_highperformance	String	Definition Whether an image supports high-performance computing. Range If an image supports high-performance computing, the value is true. Otherwise, this parameter is not required.
__support_xen_gpu_type	String	Definition Whether an image supports GPUs on the Xen platform. For details, see Table 2. Range If an image supports GPUs on the Xen platform, the value is true. Otherwise, this parameter is not required.
__support_kvm_gpu_type	String	Definition Whether an image supports GPUs on the KVM platform. For details, see Table 3. Range If an image supports GPUs on the KVM platform, the value is true. Otherwise, this parameter is not required.
__support_xen_hana	String	Definition Whether an image supports HANA on the Xen platform. Range If an image supports HANA on the Xen platform, the value is true. Otherwise, this parameter is not required.
__support_kvm_infiniband	String	Definition Whether an image supports InfiniBand NICs on the KVM platform. Range If an image supports InfiniBand NICs on the KVM platform, the value is true. Otherwise, this parameter is not required.
__system_support_market	Boolean	Definition Whether an image can be published in KooGallery. Range true: supported false: not supported
__is_offshelved	String	Definition Whether the KooGallery image has been taken offline. Range true: The image has been taken offline. false: The image has not been taken offline.
enterprise_project_id	String	Definition Enterprise project that an image belongs to. For more information about enterprise projects, see Enterprise Center. For details about how to obtain an enterprise project ID, see How Do I Obtain an Enterprise Project ID? Range If the value is 0 or left blank, the image belongs to the default enterprise project. If the value is a UUID, the image belongs to the enterprise project corresponding to the UUID.
__root_origin	String	Definition Origin of an image. Range file: The image is created from a file.
__sequence_num	String	Definition Cloud server system disk slot. Range N/A
__support_fc_inject	String	Definition Whether an image supports password/private key injection with Cloud-Init. NOTE: This parameter is only valid for ECS system disk images. Range true indicates password/private key injection using Cloud-Init is not supported. Other values indicate the injection is supported.
hw_firmware_type	String	Definition Cloud server boot mode. Range The value can be: bios indicates the BIOS boot mode. uefi indicates the UEFI boot mode.
hw_vif_multiqueue_enabled	String	Definition Whether an image supports NIC multi-queue. Range The value can be true or false. true: NIC multi-queue is supported. false: NIC multi-queue is not supported.
__support_arm	String	Definition Whether an image uses the Arm architecture. Range The value can be true or false. true: The Arm architecture is used. false: The Arm architecture is not used.
__support_agent_list	String	Definition Agents configured for an image. Range hss: server security ces: server monitoring Example value: "__support_agent_list": "hss,ces" NOTE: If the response does not contain this field, the HSS or host monitoring agents are not configured for the image.
__system__cmkid	String	Definition ID of the key used for image encryption. Range N/A
__account_code	String	Definition Image charging flag. Range N/A
__support_amd	String	Definition Whether the image architecture is AMD. Range The value can be true or false. true: The AMD architecture is used. false: The AMD architecture is not used.
__support_kvm_hi1822_hisriov	String	Definition Whether an image supports SR-IOV passthrough. Range If an image supports SR-IOV passthrough, the value is true. Otherwise, this parameter is not required.
__support_kvm_hi1822_hivirtionet	String	Definition Whether an image supports VirtIO-Net passthrough. Range If an image supports VirtIO-Net passthrough, the value is true. Otherwise, this parameter is not required.
os_shutdown_timeout	String	Definition Graceful shutdown timeout period. You are advised to set this parameter to 120 for Linux images and 600 for Windows images. After a graceful shutdown times out, a forced shutdown will be triggered to prevent a cloud server from staying in a pending shutdown state for a long time. Your cloud server may keep staying in a graceful shutdown state due to running software or unsaved work when you stop the server. This will trigger a forced shutdown. You can set this parameter to a larger value to provide a longer graceful shutdown timeout duration. This parameter only applies to ECSs and does not apply to BMSs. Range The value is an integer ranging from 60 to 1200, in seconds.

**Table 3** Data structure description of the page_info field
Parameter	Type	Description
next_marker	String	Definition Marker for querying the next page. The value is an image ID. If a value is returned for this field in the response, there is data on the next page. Range N/A

Example response

STATUS CODE 200

     {
  "images": [
    {
      "schema": "/v2/schemas/image",
      "min_disk": 100,
      "created_at": "2018-09-06T14:03:27Z",
      "__image_source_type": "uds",
      "container_format": "bare",
      "file": "/v2/images/bc6bed6e-ba3a-4447-afcc-449174a3eb52/file",
      "updated_at": "2018-09-06T15:17:33Z",
      "protected": true,
      "checksum": "d41d8cd98f00b204e9800998ecf8427e",
      "id": "bc6bed6e-ba3a-4447-afcc-449174a3eb52",
      "__isregistered": "true",
      "min_ram": 2048,
      "__lazyloading": "true",
      "owner": "1bed856811654c1cb661a6ca845ebc77",
      "__os_type": "Linux",
      "__imagetype": "gold",
      "visibility": "public",
      "virtual_env_type": "FusionCompute",
      "tags": [],
      "__platform": "CentOS",
      "size": 0,
      "__os_bit": "64",
      "__os_version": "CentOS 7.3 64bit",
      "name": "CentOS 7.3 64bit vivado",
      "self": "/v2/images/bc6bed6e-ba3a-4447-afcc-449174a3eb52",
      "disk_format": "zvhd2",
      "virtual_size": null,
      "hw_firmware_type": "bios",
      "status": "active",
      "__support_fc_inject":"true"
    },
    {
      "schema": "/v2/schemas/image",
      "min_disk": 100,
      "created_at": "2018-09-06T14:03:05Z",
      "__image_source_type": "uds",
      "container_format": "bare",
      "file": "/v2/images/0328c25e-c840-4496-81ac-c4e01b214b1f/file",
      "updated_at": "2018-09-25T14:27:40Z",
      "protected": true,
      "checksum": "d41d8cd98f00b204e9800998ecf8427e",
      "id": "0328c25e-c840-4496-81ac-c4e01b214b1f",
      "__isregistered": "true",
      "min_ram": 2048,
      "__lazyloading": "true",
      "owner": "1bed856811654c1cb661a6ca845ebc77",
      "__os_type": "Linux",
      "__imagetype": "gold",
      "visibility": "public",
      "virtual_env_type": "FusionCompute",
      "tags": [],
      "__platform": "CentOS",
      "size": 0,
      "__os_bit": "64",
      "__os_version": "CentOS 7.3 64bit",
      "name": "CentOS 7.3 64bit with sdx",
      "self": "/v2/images/0328c25e-c840-4496-81ac-c4e01b214b1f",
      "disk_format": "zvhd2",
      "virtual_size": null,
      "hw_firmware_type": "bios",
      "status": "active",
      "__support_fc_inject":"true"
    }
  ],
  "page_info": [
    {
      "next_marker": "0328c25e-c840-4496-81ac-c4e01b214b1f"
    }
  ] 
}
 
 
  

Returned Values

Normal
200

Abnormal

Returned Value	Description
400 Bad Request	Request error. For details, see Error Codes.
401 Unauthorized	Authentication failed.
403 Forbidden	You do not have the rights to perform the operation.
404 Not Found	The requested resource was not found.
500 Internal Server Error	Internal service error.
503 Service Unavailable	The service is unavailable.

Parent topic: Image

Previous topic: Image

Next topic: Updating an Image