Scan Status.

Get the current status and progress of a scan. Poll this endpoint every 3-5 seconds until status reaches a terminal state.

Authentication

Requires a valid API key. You can only access scans created with your API key or within your organization.

Path parameters

Status values

Response — scanning

{
  "id": "scan_abc123",
  "status": "scanning",
  "type": "security",
  "url": "https://example.com",
  "progress": 45,
  "events": [
    { "time": "12:00:05", "message": "Starting HSTS check" },
    { "time": "12:00:08", "message": "Starting CSP check" },
    { "time": "12:00:12", "message": "Starting cookie analysis" }
  ],
  "created_at": "2026-03-30T12:00:00Z"
}

Response — completed

{
  "id": "scan_abc123",
  "status": "completed",
  "type": "security",
  "url": "https://example.com",
  "progress": 100,
  "result": {
    "score": 72,
    "grade": "C",
    "report_url": "/report/scan_abc123"
  },
  "created_at": "2026-03-30T12:00:00Z",
  "completed_at": "2026-03-30T12:01:15Z"
}

Response — failed

{
  "id": "scan_abc123",
  "status": "failed",
  "type": "security",
  "url": "https://example.com",
  "error": "Target URL returned HTTP 503 — site appears to be down.",
  "created_at": "2026-03-30T12:00:00Z"
}

Polling pattern

Poll every 3-5 seconds. Stop when status is completed, partial, or failed. Here is a cURL polling loop:

# Poll until terminal state
SCAN_ID="scan_abc123"
while true; do
  RESP=$(curl -s https://appvet.dev/v1/scan/$SCAN_ID \
    -H "Authorization: Bearer avk_live_your_key_here")
  STATUS=$(echo $RESP | jq -r '.status')
  echo "Status: $STATUS"
  case $STATUS in
    completed|partial|failed) break ;;
  esac
  sleep 5
done
echo $RESP | jq .

Error responses