> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# List Image Versions

> Lists the versions of an image, newest first. Each successful build is a new version of the same image.

Needs the `images:read` scope when called with an API key.

**image\_id** `string` *required*

The image ID.

**workspace\_id** `string`

If the image belongs to a workspace, the workspace's ID. Required for workspace members acting on an image they don't own.

### Response

**response** `array`

An array of versions, newest first.

**Toggle object**

**id** `string`

The version ID. Use it as `version_id` to read the build log of that version.

**digest** `string`

Digest (`sha256:...`) of the version.

**source** `string`

What triggered the build: `upload` (a full context uploaded), `commit` (files committed on top of the current context) or `github` (a push to the linked branch).

**message** `string | null`

The message sent with the upload or commit, or `null`.

**created\_at** `string`

When the version was built.

**in\_use** `boolean`

`true` when at least one application runs this version.

```json Response theme={null}
{
  "response": [
    {
      "id": "imgv-111aaa222bbb",
      "digest": "sha256:3f1c0a9d5b7e2c4a8d6f1b0e9c3a7d5f2b4e6a8c0d1f3b5a7c9e2d4f6a8b0c1e",
      "source": "upload",
      "message": "first build",
      "created_at": "2026-10-23T14:09:00Z",
      "in_use": true
    }
  ]
}
```

> [!NOTE]
>
> An application keeps up to 30 releases for 30 days on the Enterprise plans, and each release points to one image version. Roll back an application with [Rollback Application](https://docs.vertracloud.app/api-reference/endpoint/apps/releases/rollback.md). A version is only removed when no release of any app uses it and it is not the current one.

### Error Responses

**code** `string`

The error code indicating the reason for the failure. Possible values:

* `API_KEY_SCOPE_DENIED`: The API key does not have the required scope (`403`).
* `IMAGE_NOT_FOUND`: The image does not exist or you cannot access it (`404`).
* `INTERNAL_SERVER_ERROR`: Unexpected failure (`500`).

```json Error Response theme={null}
{
  "code": "IMAGE_NOT_FOUND"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.