---
title: "List User Images"
method: GET
path: "/api/v1/images"
tags: ["Images"]
---

# List User Images

`GET /api/v1/images`

List images and builds for the current user, scoped by team context. Returns personal images by default, or team images if teamId is provided.

Pagination note: `limit`, `offset`, and `totalCount` count logical images
(unique `owner/imageName:imageTag`). A single image may produce multiple
`data[]` rows (one per artifact type plus any active builds), so
`len(data)` can exceed `limit` and `totalCount` reflects images, not rows.

The optional `search` parameter narrows results (case-insensitively) to
images whose name, tag, or `name:tag` reference contains the given
substring.

Setting `ownerScope=platform` lists only org-less platform images and
builds; this requires platform admin access.

## Query parameters

- `teamId` string, nullable — Filter by team ID. If provided, returns only that team's images. If not provided, returns only personal images.
- `search` string, nullable — Case-insensitive substring match on image name, tag, or the displayed reference.
- `ownerScope` 'team' | 'personal' | 'platform'
- `offset` integer
- `limit` integer

## Response `200`

Successful Response

- GenericPaginationResponseListImageResponse
  - `total_count` integer — Total number of items available in the dataset
  - `offset` integer — Number of items to skip before starting to collect the result set
  - `limit` integer — Maximum number of items to return
  - `data` ImageResponse[], required
    - `id` string, required — Unique identifier for the image
    - `artifactType` 'CONTAINER_IMAGE' | 'VM_SANDBOX'
    - `imageName` string, required — Name of the image
    - `imageTag` string, required — Tag of the image
    - `status` 'PENDING' | 'UPLOADING' | 'BUILDING' | 'COMPLETED' | 'FAILED' | 'CANCELLED', required
    - `fullImagePath` string, nullable — Stored output reference for the image artifact
    - `errorMessage` string, nullable — Error message if build failed
    - `sizeBytes` integer, nullable — Size of the image in bytes
    - `visibility` 'PRIVATE' | 'PUBLIC'
    - `createdAt` string, date-time, required — Timestamp when the build was created
    - `startedAt` string, date-time, nullable — Timestamp when the build started
    - `completedAt` string, date-time, nullable — Timestamp when the build completed
    - `pushedAt` string, date-time, nullable — Timestamp when the image artifact was registered
    - `teamId` string, nullable — Team ID if this is a team image
    - `ownerType` 'team' | 'personal' | 'platform'
    - `displayRef` string, nullable — User-friendly reference: prime/{team/user slug}/name:tag for owned images, falling back to ids, or name:tag for platform images
  - `status` string, nullable — Response status

## Other responses

- `401` — Authorization failed
- `422` — Invalid request data

---

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