---
title: "Get the status of a scan"
method: GET
path: "/api/v1/app/{appId}/perch/status"
tags: ["Perch"]
---

# Get the status of a scan

`GET /api/v1/app/{appId}/perch/status`

## Get Scan Status

Returns the current status of the cloud-based security scan for the given application ID.

This endpoint provides real-time information about the current state of a scan, including whether it's running, completed, or encountered any errors. Use this endpoint to monitor scan progress and determine when results are available.

### Prerequisites

- The `CLOUD_SCANNING` feature flag must be enabled
- User must have access to the specified application

### Response



| Parameter | Default | Description |
|:---:|:---:|:---:|
|device|{}||

```json
{
	"device": {}
}
```

### Scan Status Values

The device status can be one of the following:

- **ONLINE**: Scan infrastructure is online and ready
- **RUNNING**: Scan is currently active and running
- **HEARTBEAT**: Scan infrastructure is active with heartbeat signals
- **HOSTED_SCANNER_DISCONNECTED**: Scan has been stopped or disconnected
- **HOSTED_SCANNER_PROVISIONING**: Scan infrastructure is being provisioned
- **HOSTED_SCANNER_ERRORED**: Scan encountered an error

### No Active Scan

If no scan has been started for the application, the endpoint will return an empty response with default values.

### Errors

- **404 Not Found**: Application not found or user doesn't have access
- **500 Internal Server Error**: Error occurred while retrieving scan status

> 👥 Teams Supported
> If the application belongs to a StackHawk [Team](https://docs.stackhawk.com/web-app/teams.html), only members of the Team can call this endpoint.


> Requires `read:device` permission.

## Path parameters

- `appId` string, uuid, required

## Response `200`

OK

- PerchGetPerchDeviceResponse
  - `device` PerchPerchDevice
    - `applicationId` string
    - `command` PerchPerchCommand
      - `command` 'NOOP' | 'SCAN_START' | 'SCAN_STOP' | 'RESCAN_START' | 'SCREENR_START_BROWSER' | 'SCREENR_START_MCP' | 'SCREENR_START_SCREENR' | 'SCREENR_START_AUTH_ANALYSIS' | 'SCREENR_EXPORT_SESSION' | 'SCREENR_STOP' | 'CONFIG_VALIDATE' | 'AUTH_VALIDATE'
      - `config` string
      - `errors` PerchPerchError[]
        - `errorType` 'UNKNOWN' | 'AUTHENTICATION' | 'PROVISIONING' | 'DEVICE'
        - `message` string
      - `id` string
      - `name` string
    - `configValidationResult` PerchConfigValidationResult
      - `errors` string[]
      - `fieldErrors` PerchValidationFieldError[]
        - `fieldName` string
        - `jsonPath` string
        - `message` string
      - `message` string
      - `success` boolean
    - `createdDate` integer
    - `deviceAddress` string
    - `id` string
    - `name` string
    - `orgId` string
    - `podType` 'HAWKSCAN' | 'SCREENR' | 'PROFILE' | 'CONFIG_VALIDATION' | 'SCAN'
    - `scanId` string
    - `status` string
    - `updatedDate` integer
    - `userId` string

## Other responses

- `401` — Unauthorized

---

[API](https://skmtc.net/stackhawk/apis/stackhawk-public-api.md) · [All operations](https://skmtc.net/stackhawk/apis/stackhawk-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stackhawk/stackhawk-public-api/versions/ad3dfd54cb63/schema)