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

**Get the status of a scan**

## 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.

## Parameters

- `appId` (in: path, string<uuid>) *(required)* — UUID identifier for this StackHawk Application.

## Responses

### 200 — OK

#### application/json

- `device` (perch.PerchDevice)
  - `applicationId` (string)
  - `command` (perch.PerchCommand)
    - `command` (string)
    - `config` (string)
    - `errors` (perch.PerchError[])
      - `errorType` (string)
      - `message` (string)
    - `id` (string)
    - `name` (string)
  - `configValidationResult` (perch.ConfigValidationResult)
    - `errors` (string[])
    - `fieldErrors` (perch.ValidationFieldError[])
      - `fieldName` (string)
      - `jsonPath` (string)
      - `message` (string)
    - `message` (string)
    - `success` (boolean)
  - `createdDate` (integer<int64>)
  - `deviceAddress` (string)
  - `id` (string)
  - `name` (string)
  - `orgId` (string)
  - `podType` (string)
  - `scanId` (string)
  - `status` (string)
  - `updatedDate` (integer<int64>)
  - `userId` (string)

#### application/x-protobuf

- `device` (perch.PerchDevice)
  - `applicationId` (string)
  - `command` (perch.PerchCommand)
    - `command` (string)
    - `config` (string)
    - `errors` (perch.PerchError[])
      - `errorType` (string)
      - `message` (string)
    - `id` (string)
    - `name` (string)
  - `configValidationResult` (perch.ConfigValidationResult)
    - `errors` (string[])
    - `fieldErrors` (perch.ValidationFieldError[])
      - `fieldName` (string)
      - `jsonPath` (string)
      - `message` (string)
    - `message` (string)
    - `success` (boolean)
  - `createdDate` (integer<int64>)
  - `deviceAddress` (string)
  - `id` (string)
  - `name` (string)
  - `orgId` (string)
  - `podType` (string)
  - `scanId` (string)
  - `status` (string)
  - `updatedDate` (integer<int64>)
  - `userId` (string)

### 401 — Unauthorized

- (no body)