Back to guides list

6.1. Listing images

GET /v2/images

List virtual machine images.

Use filters to list only the images you need. For example, to list all images in a placement, append the following to the request:

?trait:CUSTOM_HCI_<UUID>=required

Source: https://docs.openstack.org/api-ref/image/v2/index.html?expanded=#list-images

6.1.1. Request

Name In Type Description
limit (Optional) query integer Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
marker (Optional) query string The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
name (Optional) query string Filters the response by a name, as a string. A valid value is the name of an image.
owner (Optional) query string Filters the response by a project (also called a “tenant”) ID. Shows only images that are shared with you by the specified owner.
protected (Optional) query boolean Filters the response by the ‘protected’ image property. A valid value is one of ‘true’, ‘false’ (must be all lowercase). Any other value will result in a 400 response.
status (Optional) query integer Filters the response by an image status.
tag (Optional) query string Filters the response by the specified tag value. May be repeated, but keep in mind that you’re making a conjunctive query, so only images containing all the tags specified will appear in the response.
visibility (Optional) query string Filters the response by an image visibility value. A valid value is public, private, community, shared, or all. (Note that if you filter on shared, the images included in the response will only be those where your member status is accepted unless you explicitly include a member_status filter in the request.) If you omit this parameter, the response shows public, private, and those shared images with a member status of accepted.
os_hidden (Optional) query boolean When true, filters the response to display only “hidden” images. By default, “hidden” images are not included in the image-list response. (Since Image API v2.7)
member_status (Optional) query string Filters the response by a member status. A valid value is accepted, pending, rejected, or all. Default is accepted.
size_max (Optional) query string Filters the response by a maximum image size, in bytes.
size_min (Optional) query string Filters the response by a minimum image size, in bytes.
created_at (Optional) query string

Specify a comparison filter based on the date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, is the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

If you omit the time zone, the UTC time zone is assumed.
updated_at (Optional) query string

Specify a comparison filter based on the date and time when the resource was most recently modified.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, is the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

If you omit the time zone, the UTC time zone is assumed.
sort_dir (Optional) query string Sorts the response by a set of one or more sort direction and attribute (sort_key) combinations. A valid value for the sort direction is asc (ascending) or desc (descending). If you omit the sort direction in a set, the default is desc.
sort_key (Optional) query string Sorts the response by an attribute, such as name, id, or updated_at. Default is created_at. The API uses the natural sorting direction of the sort_key image attribute.
sort (Optional) query string

Sorts the response by one or more attribute and sort direction combinations. You can also set multiple sort keys and directions. Default direction is desc.

Use the comma (,) character to separate multiple values. For example:

GET /v2/images?sort=name:asc,status:desc

6.1.1.1. Example

# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<>' \
https://<node_IP_addr>:9292/v2/images

6.1.2. Response

Name In Type Description
images body array A list of image objects.
first body string The URI for the first page of response.
next body string The URI for the next page of response. Will not be present on the last page of the response.
schema body string The URL for the schema describing a list of images.

6.1.2.1. Status codes

6.1.2.1.1. Success

Code Reason
200 - OK Request was successful.

6.1.2.1.2. Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
403 - Forbidden Policy does not allow current user to do this operation.

6.1.2.2. Example

{
  "images": [
    {
      "image_validated": "yes",
      "container_format": "bare",
      "min_ram": 0,
      "updated_at": "2020-02-04T10:58:47Z",
      "file": "/v2/images/c92d820c-50dc-4fd1-a0bc-2f1071487b67/file",
      "owner": "f5d834d636c642c7bfe8af86139c6f26",
      "id": "c92d820c-50dc-4fd1-a0bc-2f1071487b67",
      "size": 12716032,
      "os_distro": "linux",
      "self": "/v2/images/c92d820c-50dc-4fd1-a0bc-2f1071487b67",
      "disk_format": "qcow2",
      "os_hash_algo": "sha512",
      "direct_url": "file:///mnt/vstorage/vols/datastores/glance/c92d820c-<...>",
      "hw_disk_bus": "virtio",
      "schema": "/v2/schemas/image",
      "status": "active",
      "tags": [],
      "trait:CUSTOM_HCI_122E856B9E9C4D80A0F8C21591B5AFCB": "required",
      "visibility": "public",
      "min_disk": 1,
      "virtual_size": null,
      "name": "cirros",
      "checksum": "443b7623e27ecf03dc9e01ee93f67afe",
      "created_at": "2020-01-28T12:58:17Z",
      "os_hidden": false,
      "protected": false,
      "os_hash_value": "6513f21e44aa3da349f248188a<...>",
      "os_type": "linux"
    }
  ],
  "schema": "/v2/schemas/images",
  "first": "/v2/images"
}
Version 5.0.0 — Feb 01, 2022
Print