---
title: "List images, newest first. With name, that name's versions."
method: GET
path: "/v1/images"
tags: ["images"]
---

# List images, newest first. With name, that name's versions.

`GET /v1/images`

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/images`
- Auth: HTTP bearer

## Query parameters

- `cursor` string: Resource identifier (UUID).
- `limit` integer: Page size, 1 to 100.
- `state` 'queued' | 'building' | 'ready' | 'failed' | 'deleting'
- `name` string: Your own handle for the resource. Letters, digits, dot, dash, underscore.

## Response `200`

Success

- object
  - `data` object[], required
    - `id` string, required
    - `kind` 'image', required
    - `status` string, required
    - `state` 'queued' | 'building' | 'ready' | 'failed' | 'deleting' | 'deleted', required
    - `name` string, nullable
    - `version` integer, nullable
    - `tags` string[]
    - `sizeBytes` integer, nullable: The image's whole file, once it is ready. Its storage is charged on this.
    - `sizeMiB` integer, nullable
    - `storedBytes` integer, nullable: The part of the file that shares nothing with other files on its server, measured when it was built; often 0, since an image is built on a shared base. Not what it is charged on: sizeBytes is.
    - `error` string, nullable
    - `createdAt` string
  - `nextCursor` string, nullable, required: Pass as cursor; null ends the list.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)