---
title: "List container images"
method: POST
path: "/api/v2/containerImages/list"
tags: ["Container Scanning"]
---

# List container images

`POST /api/v2/containerImages/list`

## Request

- Base URL: `https://zeropath.com`
- URL: `https://zeropath.com/api/v2/containerImages/list`
- Auth: API key in header `X-ZeroPath-API-Token-Id` and API key in header `X-ZeroPath-API-Token-Secret`

List tracked container images with cursor-based pagination, each with its latest scan summary. Optionally filter by repositoryId. Powers the Containers tab.

## Request body

- ContainerImagesListRequest: Input for listing tracked container images with cursor-based pagination.
  - `organizationId` string: Organization ID (optional).
  - `repositoryId` string: Filter to a specific repository.
  - `search` string: Case-insensitive free-text filter matched against the image reference and its linked repository name.
  - `cursor` string: Pagination cursor from a previous nextCursor.
  - `limit` number: Number of items to return.

## Response `200`

Container images retrieved

- ContainerImagesListResponse
  - `items` ContainerImageGetResponse[], required
    - `image` ContainerImage, required: A container image tracked by an organization (via its repository).
      - `id` string, required
      - `repositoryId` string, required: Repository the image is scoped to. For images submitted without a real repository this is an ephemeral standalone repository.
      - `repositoryName` string, nullable, required: Display name of the real ZeroPath repository the image is linked to, or null when the image is only attached to an ephemeral standalone repository (submitted without a real repo).
      - `imageSource` 'REGISTRY' | 'UPLOADED_ARCHIVE', required: Where the image bytes come from. REGISTRY images are pulled by reference (registryHost set, optional private auth); UPLOADED_ARCHIVE images are scanned from an uploaded tarball (registryHost null, never any auth, never monitored).
      - `imageRef` string, required: For REGISTRY images, the full image reference as submitted, e.g. "ghcr.io/acme/api:1.4". For UPLOADED_ARCHIVE images, the user-supplied display label.
      - `registryHost` string, nullable, required: Registry host parsed from imageRef for REGISTRY images, e.g. "ghcr.io" or "docker.io". Null for UPLOADED_ARCHIVE images (no registry is involved).
      - `registryUsername` string, nullable, required: Username configured for pulling a private REGISTRY image, or null for anonymous pulls and uploaded archives. The registry token is encrypted at rest and is NEVER returned.
      - `registryConnection` object, nullable, required: Org-level registry connection supplying pull credentials for this image, or null when the image pulls anonymously or with inline credentials. Mutually exclusive with inline registryUsername/registryToken. Only the non-secret identity is exposed.
        - `id` string, required
        - `displayName` string, required
      - `hasRegistryAuth` boolean, required: True when private-registry credentials are configured for this image — either an inline token or a linked org-level registry connection. No secret is ever exposed.
      - `lastResolvedDigest` string, nullable: Digest resolved at the most recent successful pull. Null until first scan.
      - `monitoringCrontab` string, nullable, required: Cron expression for recurring re-scans, or null when monitoring is off (scan-on-submit only). Its presence is the monitoring state: monitored iff non-null.
      - `track` 'EDGE' | 'STABLE', required: Release track of the worker pool that scans this image.
      - `lastScannedAt` string, date-time, nullable
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
    - `latestScan` ContainerScanSummary, required: Summary of a single container scan, as surfaced next to its image.
      - `id` string, required
      - `status` 'IMAGE_PULL' | 'LAYER_ANALYSIS' | 'VULN_DETECTION' | 'SUCCEEDED' | 'FAILED', required: Lifecycle status. IMAGE_PULL/LAYER_ANALYSIS/VULN_DETECTION are running phases; SUCCEEDED and FAILED are terminal.
      - `errored` boolean, required: True when the scan failed (status === FAILED). A failed scan is terminal: stop polling.
      - `findingsCount` number, required: Number of vulnerabilities detected by this scan.
      - `detectedBaseImageRef` string, nullable: Base image detected from layer history, e.g. "node:18-bookworm".
      - `recommendedBaseImageRef` string, nullable: Recommended base-image upgrade that would remove the most findings.
      - `recommendedBaseImageVulnReduction` number, nullable: Number of findings the recommended base-image upgrade would remove.
    - `queued` boolean, required: True when a scan is enqueued (a StagedContainerScan exists) and not yet promoted to a running ContainerScan. Stays true for a re-scan even if a prior finished scan exists, so callers wait for the new run.
  - `nextCursor` string, nullable, required
  - `hasMore` boolean, required

## Other responses

- `401`: Error Response

---

[API](https://skmtc.dev/zeropath/apis/zeropath-api.md) - [All operations](https://skmtc.dev/zeropath/apis/zeropath-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zeropath/apis/zeropath-api/revisions/126e9c80ba0d?raw)