---
title: "Get a container image"
method: POST
path: "/api/v2/containerImages/get"
tags: ["Container Scanning"]
---

# Get a container image

`POST /api/v2/containerImages/get`

## Request

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

Retrieve a tracked container image with its latest scan summary and queue state. The `queued` flag is true when a scan is enqueued but no ContainerScan exists yet; `latestScan` is null until the first scan runs. This is the endpoint to poll after containerScans.submit.

## Request body

- ContainerImageGetRequest: Input for getting a tracked container image and its latest scan summary.
  - `organizationId` string: Organization ID (optional).
  - `containerImageId` string, required: ID of the container image.

## Response `200`

Container image retrieved

- ContainerImageGetResponse: A tracked container image with its latest scan summary and queue state.
  - `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.

## Other responses

- `401`: Error Response
- `404`: 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)