Trigger and monitor scans

Start security scans programmatically and poll for results.

Trigger a scan

bash

POST /api/v1/scans
Authorization: Bearer <token>
X-Tenant-Slug: my-company
Content-Type: application/json

{"connection_id": "conn_abc123"}

json

{
  "id": "scan_xyz789",
  "status": "queued",
  "provider": "aws",
  "connection_alias": "Production AWS",
  "started_at": null
}

Poll scan status

Poll GET /scans/{scan_id} until status is completed or failed:

python

import time, requests

def wait_for_scan(scan_id, token, workspace):
    headers = {
        "Authorization": f"Bearer {token}",
        "X-Tenant-Slug": workspace,
    }
    while True:
        r = requests.get(
            f"https://api.fixmycloud.ai/api/v1/scans/{scan_id}",
            headers=headers
        )
        scan = r.json()
        if scan["status"] in ("completed", "failed"):
            return scan
        print(f"Status: {scan['status']} — waiting...")
        time.sleep(10)

Scan status values

queuedScan is waiting for a worker

runningScan is actively checking infrastructure

completedScan finished successfully

failedScan encountered an error

Completed scan result

json

{
  "id": "scan_xyz789",
  "status": "completed",
  "provider": "aws",
  "total_findings": 47,
  "critical_count": 3,
  "high_count": 12,
  "medium_count": 22,
  "low_count": 10,
  "risk_score": 72.4,
  "started_at": "2026-04-12T10:30:00Z",
  "completed_at": "2026-04-12T10:34:12Z"
}

Tip: Instead of polling, set up a webhook to receive scan completion events automatically. See the webhooks guide.