Give Feedback

pydo.images.list()

Generated on 8 May 2026 from pydo version v0.34.0

Copy page as Markdown View page as Markdown

Usage

client.images.list(
    type=None,
    private=None,
    tag_name=None,
    per_page=20,
    page=1,
)

Returns JSONRaises HttpResponseError

Description

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.

Parameters

type string optional

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

One of: application, distribution

private boolean optional

Used to filter only user images.

tag_name string optional

Used to filter images by a specific tag.

per_page integer optional

Number of items returned per page

Min: 1

Max: 200

Default: 20

page integer optional

Which 'page' of paginated results to return.

Min: 1

Default: 1

Request Sample

Show Request Sample

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

resp = client.images.list()

Pagination

This method returns paginated results. The response includes a links.pages object with URLs for navigating between pages. To retrieve the next page, parse the next URL and pass the page parameter:

from urllib.parse import urlparse, parse_qs

resp = client.images.list()
pages = resp.get("links", {}).get("pages", {})

while "next" in pages:
    parsed = urlparse(pages["next"])
    page = int(parse_qs(parsed.query)["page"][0])
    resp = client.images.list(page=page)
    pages = resp.get("links", {}).get("pages", {})

Response Example

Show Response 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
  }
}

More Information

See /v2/images in the API reference for additional detail on responses, headers, parameters, and more.