> ## Documentation Index
> Fetch the complete documentation index at: https://docs.binarly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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/{product_id}/images/{image_id}/scans?status=true
```

**Endpoint - Get a Specific Scan**

```
GET <BINARLY_API_URL>/api/v4/products/{product_id}/images/{image_id}/scans/{scan_id}?status=true
```

**Path Parameters**

| Parameter    | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `product_id` | The product ID (e.g., `prod_abc123`)                       |
| `image_id`   | The image ID returned from the upload (e.g., `img_abc123`) |
| `scan_id`    | (Optional) Specific scan ID to query                       |

**Query Parameters**

| Parameter | Required | Description                                      |
| --------- | -------- | ------------------------------------------------ |
| `status`  | ✅        | Set to `true` to include scan status information |

**Headers**

| Header          | Value                   |
| --------------- | ----------------------- |
| `Authorization` | `Bearer <access_token>` |

## Example Request

```bash theme={null}
# Set your variables (from the upload response)
BINARLY_PRODUCT_ID="prod_abc123"
IMAGE_ID="img_abc123"

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

## Response

```json theme={null}
{
  "scans": [
    {
      "id": "scan_xyz789",
      "createTime": "2026-01-26T15:30:01Z",
      "latestScanState": {
        "type": "in_progress"
      }
    }
  ]
}
```

## Scan States

The status is found in the `latestScanState.type` field:

| State                | Description                    | Action                        |
| -------------------- | ------------------------------ | ----------------------------- |
| `in_progress`        | Analysis is currently running  | Wait and poll again           |
| `completed`          | Analysis finished successfully | Results are ready to view     |
| `no_scans`           | No scans exist for the image   | Check if upload succeeded     |
| `status_unavailable` | Status could not be determined | Contact support if persistent |

## Polling for Completion

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

```bash theme={null}
# Poll every 30 seconds until scan completes
while true; do
  STATUS=$(curl -s -H "Authorization: Bearer ${TOKEN}" \
    "${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images/${IMAGE_ID}/scans?status=true" \
    | jq -r '.scans[0].latestScanState.type')
  
  echo "Current status: $STATUS"
  
  if [ "$STATUS" = "completed" ]; then
    echo "✅ Scan completed!"
    break
  elif [ "$STATUS" = "in_progress" ]; then
    echo "⏳ Still scanning... waiting 30 seconds"
    sleep 30
  else
    echo "❌ Unexpected status: $STATUS"
    break
  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         |

> **Tip:** For large images, consider setting up webhook notifications instead of polling.