---
title: "List All Images"
method: GET
path: "/v2/images"
tags: ["DigitalOcean-public.v2-new_Images"]
---

# 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

- `type` 'application' | 'distribution'
- `private` boolean
- `tag_name` string
- `per_page` integer
- `page` integer

## Response `200`

The response will be a JSON object with a key called `images`.  This will be set to an array of image objects, each of which will contain the standard image attributes.

- object
  - `images` Image[], required
    - `id` integer — A unique number that can be used to identify and reference a specific image.
    - `name` string — The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question.
    - `type` 'base' | 'snapshot' | 'backup' | 'custom' | 'admin' — Describes the kind of image. It may be one of `base`, `snapshot`, `backup`, `custom`, or `admin`. Respectively, this specifies whether an image is a DigitalOcean base OS image, user-generated Droplet snapshot, automatically created Droplet backup, user-provided virtual machine image, or an image used for DigitalOcean managed resources (e.g. DOKS worker nodes).
    - `distribution` 'Arch Linux' | 'CentOS' | 'CoreOS' | 'Debian' | 'Fedora' | 'Fedora Atomic' | 'FreeBSD' | 'Gentoo' | 'openSUSE' | 'RancherOS' | 'Rocky Linux' | 'Ubuntu' | 'Unknown' — The name of a custom image's distribution. Currently, the valid values are `Arch Linux`, `CentOS`, `CoreOS`, `Debian`, `Fedora`, `Fedora Atomic`, `FreeBSD`, `Gentoo`, `openSUSE`, `RancherOS`, `Rocky Linux`, `Ubuntu`, and `Unknown`. Any other value will be accepted but ignored, and `Unknown` will be used in its place.
    - `slug` string, nullable — A uniquely identifying string that is associated with each of the DigitalOcean-provided public images. These can be used to reference a public image as an alternative to the numeric id.
    - `public` boolean — This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account.
    - `regions` RegionSlug[] — This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values.
    - `created_at` string, date-time — A time value given in ISO8601 combined date and time format that represents when the image was created.
    - `min_disk_size` integer, nullable — The minimum disk size in GB required for a Droplet to use this image.
    - `size_gigabytes` number, float, nullable — The size of the image in gigabytes.
    - `description` string — An optional free-form text field to describe an image.
    - `tags` string[], nullable — A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags. <br><br>Requires `tag:create` scope.
    - `status` 'NEW' | 'available' | 'pending' | 'deleted' | 'retired' — A status string indicating the state of a custom image. This may be `NEW`, `available`, `pending`, `deleted`, or `retired`.
    - `error_message` string — A string containing information about errors that may occur when importing a custom image.
  - `links` PageLinks
    - `pages` union
      - ForwardLinks
        - `last` string — URI of the last page of the results.
        - `next` string — URI of the next page of the results.
      - BackwardLinks
        - `first` string — URI of the first page of the results.
        - `prev` string — URI of the previous page of the results.
      - unknown
  - `meta` object, required — Information about the response itself.
    - `total` integer, required — Number of objects returned by the request.

## Other responses

- `401` — Authentication failed due to invalid credentials.
- `429` — The API rate limit has been exceeded.
- `500` — There was a server error.
- `default` — There was an unexpected error.

---

[API](https://skmtc.net/digitalocean/apis/digitalocean-api.md) · [All operations](https://skmtc.net/digitalocean/apis/digitalocean-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/digitalocean/digitalocean-api/revisions/cb3bf9b21459/schema)