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

# List container scans

`POST /api/v2/containerScans/list`

## Request

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

List container scans with cursor-based pagination, optionally filtered by repositoryId or containerImageId.

## Request body

- ContainerScansListRequest: Input for listing container scans with cursor-based pagination.
  - `organizationId` string: Organization ID (optional).
  - `repositoryId` string: Filter to a specific repository.
  - `containerImageId` string: Filter to a specific container image.
  - `cursor` string: Pagination cursor from a previous nextCursor.
  - `limit` number: Number of items to return.

## Response `200`

Container scans retrieved

- ContainerScansListResponse
  - `items` ContainerScan[], required
    - `id` string, required
    - `containerImageId` string, required
    - `repositoryId` string, required
    - `imageRef` string, required
    - `imageDigest` string, nullable
    - `imageSizeBytes` number, nullable
    - `imageCreatedAt` string, date-time, nullable: When the image was built (the image's own creation date); null when unknown.
    - `status` 'IMAGE_PULL' | 'LAYER_ANALYSIS' | 'VULN_DETECTION' | 'SUCCEEDED' | 'FAILED', required
    - `errored` boolean, required: True when the scan failed (status === FAILED). A failed scan is terminal: stop polling. The DB CHECK ((status = 'FAILED') = (genericErrorId IS NOT NULL)) guarantees this flag equals (status === FAILED) exactly.
    - `detectedBaseImageRef` string, nullable
    - `recommendedBaseImageRef` string, nullable
    - `recommendedBaseImageVulnReduction` number, nullable
    - `findingsCount` number, required
    - `layers` ContainerImageLayer[], required: Image layers ordered by layerIndex ascending.
      - `id` string, required
      - `layerDigest` string, required
      - `layerIndex` number, required: Zero-based position in the image manifest.
      - `sizeBytes` number, nullable, required: Layer size in bytes, or null when the scan engine does not report it.
      - `createdByCmd` string, nullable: Dockerfile directive that produced the layer (from image history).
      - `isBaseImageLayer` boolean, required: True when the layer belongs to the detected base image.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `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)