List Scans

Monitor the progress of security scans after uploading a binary image. Use this endpoint to check when analysis is complete.

When to Use This Endpoint

After uploading a binary image, use this endpoint to:

Check if the security scan is still in progress
Determine when analysis has completed
Get the scan ID for retrieving detailed results

Request

Endpoint - List All Scans for an Image

GET <BINARLY_API_URL>/api/v4/products/{productId}/images/{imageId}/scans

Endpoint - Get a Specific Scan

GET <BINARLY_API_URL>/api/v4/products/{productId}/images/{imageId}/scans/{scanId}

Path Parameters

Parameter	Description
`productId`	The product ID (e.g., `01JQPGDX8QW0YJ0XEKV1EVG534`)
`imageId`	The image ID returned from the upload (e.g., `01JYJ0W0AACGC7QT1Q21SRWG94`)
`scanId`	The scan ID. Only used by the second endpoint, which returns one specific scan

Headers

Header	Value
`Authorization`	`Bearer <access_token>`

Example Request

# Set your variables (from the upload response)
BINARLY_PRODUCT_ID="01JQPGDX8QW0YJ0XEKV1EVG534"
IMAGE_ID="01JYJ0W0AACGC7QT1Q21SRWG94"

# Check scan status
curl -H "Authorization: Bearer ${TOKEN}" \
  "${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/scans"

Response

Scans are listed newest first, so scans[0] is the latest scan. The example shows the main fields of each scan.

{
  "scans": [
    {
      "id": "01JZ30CYZY52F5BPR3AAJ2DP89",
      "createTime": "2026-01-26T15:30:01Z",
      "parent": "products/01JQPGDX8QW0YJ0XEKV1EVG534/images/01JYJ0W0AACGC7QT1Q21SRWG94",
      "author": {
        "id": "01JV49FS1ZSGQ72NN6E0RXK3T0",
        "userId": "01JV49FS1ZSGQ72NN6E0RXK3T0",
        "email": "user@example.com",
        "status": "active"
      },
      "latestScanState": {
        "id": "01K6Z3V9Q2M7XH4D8RTN5B1C0E",
        "type": "running",
        "createTime": "2026-01-26T15:31:12Z"
      }
    }
  ]
}

Scan States

The status is found in the latestScanState.type field:

State	Description	Action
`new`	Scan is queued and has not started	Wait and poll again
`running`	Analysis is currently running	Wait and poll again
`done`	Analysis finished successfully	Results are ready to view
`failed`	Analysis did not complete	Start a new scan or contact support
`cancelled`	Scan was cancelled before it finished	Start a new scan if needed

Polling for Completion

To wait for a scan to complete, poll the endpoint periodically:

# Poll every 30 seconds until the scan leaves the new/running states
while true; do
  STATUS=$(curl -s -H "Authorization: Bearer ${TOKEN}" \
    "${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/scans" \
    | jq -r '.scans[0].latestScanState.type')

  echo "Current status: $STATUS"

  if [ "$STATUS" = "done" ]; then
    echo "Scan completed"
    break
  elif [ "$STATUS" = "new" ] || [ "$STATUS" = "running" ]; then
    echo "Still scanning, waiting 30 seconds"
    sleep 30
  else
    echo "Scan did not finish successfully: $STATUS"
    exit 1
  fi
done

Scan Duration

Scan duration depends on the binary image size, complexity and content:

Image Size	Typical Duration
< 64 MB	5-10 minutes
64-500 MB	10-60 minutes
> 500 MB	1+ hours

Overview

Use Cases

Reference