Skip to content
Gradient SDK Docs
  • Auto
  • Light
  • Dark

List

List All Images
get/v2/images

To list all of the images available on your account, send a GET request to /v2/images.

Filtering Results

It's possible to request filtered results by including certain query parameters.

Image Type

Either 1-Click Application or OS Distribution images can be filtered by using the type query parameter.

Important: The type query parameter does not directly relate to the type attribute.

To retrieve only distribution images, include the type query parameter set to distribution, /v2/images?type=distribution.

To retrieve only application images, include the type query parameter set to application, /v2/images?type=application.

User Images

To retrieve only the private images of a user, include the private query parameter set to true, /v2/images?private=true.

Tags

To list all images assigned to a specific tag, include the tag_name query parameter set to the name of the tag in your GET request. For example, /v2/images?tag_name=$TAG_NAME.

Query Parameters
pagenumber
optional

Which 'page' of paginated results to return.

minimum1
per_pagenumber
optional

Number of items returned per page

minimum1
maximum200
privateboolean
optional

Used to filter only user images.

tag_namestring
optional

Used to filter images by a specific tag.

typeenum
optional
"application" OR "distribution"

Filters results based on image type which can be either application or distribution.

Hide ParametersShow Parameters
"application"
"distribution"
Returns
imagesarray of idnumbercreated_atstringdescriptionstringdistributionenumerror_messagestringmin_disk_sizenumbernamestringpublicbooleanregionsarray of enumsize_gigabytesnumberslugstringstatusenumtagsarray of stringtypeenumImage
metatotalnumberMetaProperties

Information about the response itself.

curl https://api.digitalocean.com//v2/images \
    -H "Authorization: Bearer $GRADIENTAI_API_KEY"
200 Example
{
  "images": [
    {
      "id": 7555620,
      "name": "Nifty New Snapshot",
      "distribution": "Ubuntu",
      "slug": null,
      "public": false,
      "regions": [
        "nyc2",
        "nyc3"
      ],
      "created_at": "2014-11-04T22:23:02Z",
      "type": "snapshot",
      "min_disk_size": 20,
      "size_gigabytes": 2.34,
      "description": "",
      "tags": [],
      "status": "available",
      "error_message": ""
    },
    {
      "id": 7555621,
      "name": "Another Snapshot",
      "distribution": "Ubuntu",
      "slug": null,
      "public": false,
      "regions": [
        "nyc2"
      ],
      "created_at": "2014-11-04T22:23:02Z",
      "type": "snapshot",
      "min_disk_size": 20,
      "size_gigabytes": 2.34,
      "description": "",
      "tags": [],
      "status": "available",
      "error_message": ""
    },
    {
      "id": 63663980,
      "name": "20.04 (LTS) x64",
      "distribution": "Ubuntu",
      "slug": "ubuntu-20-04-x64",
      "public": true,
      "regions": [
        "nyc2",
        "nyc3"
      ],
      "created_at": "2020-05-15T05:47:50Z",
      "type": "snapshot",
      "min_disk_size": 20,
      "size_gigabytes": 2.36,
      "description": "",
      "tags": [],
      "status": "available",
      "error_message": ""
    },
    {
      "id": 7555621,
      "name": "A custom image",
      "distribution": "Arch Linux",
      "slug": null,
      "public": false,
      "regions": [
        "nyc3"
      ],
      "created_at": "2014-11-04T22:23:02Z",
      "type": "custom",
      "min_disk_size": 20,
      "size_gigabytes": 2.34,
      "description": "",
      "tags": [],
      "status": "available",
      "error_message": ""
    },
    {
      "id": 7555621,
      "name": "An APP image",
      "distribution": "Fedora",
      "slug": null,
      "public": false,
      "regions": [
        "nyc2",
        "nyc3"
      ],
      "created_at": "2014-11-04T22:23:02Z",
      "type": "snapshot",
      "min_disk_size": 20,
      "size_gigabytes": 2.34,
      "description": "",
      "tags": [],
      "status": "available",
      "error_message": ""
    },
    {
      "id": 7555621,
      "name": "A simple tagged image",
      "distribution": "CentOS",
      "slug": null,
      "public": false,
      "regions": [
        "nyc2",
        "nyc3"
      ],
      "created_at": "2014-11-04T22:23:02Z",
      "type": "snapshot",
      "min_disk_size": 20,
      "size_gigabytes": 2.34,
      "description": "",
      "tags": [
        "simple-image"
      ],
      "status": "available",
      "error_message": ""
    }
  ],
  "links": {
    "pages": {}
  },
  "meta": {
    "total": 6
  }
}