---
title: "Stop a hosted scan"
method: POST
path: "/api/v1/app/{appId}/perch/stop"
tags: ["Perch"]
---

# Stop a hosted scan

`POST /api/v1/app/{appId}/perch/stop`

## Stop a Scan

Stops a running hosted security scan and cleans up the resources used for the scan.

This endpoint will immediately stop any running scan for the specified application and clean up the associated hosted resources. 

### Prerequisites

- A scan must be currently running for this application

### Request Body



| Parameter | Default | Description |
|:---:|:---:|:---:|
|id|""||
|name|""||
|command|{}||

### Response



| Parameter | Default | Description |
|:---:|:---:|:---:|
|id|""||
|name|""||
|status|"UNKNOWN"||

```json
{
	"id": "",
	"name": "",
	"status": "UNKNOWN"
}
```


### Status Response

The response will include a status of `HOSTED_SCANNER_DISCONNECTED` to indicate the scan has been successfully stopped.

### Errors

- **404 Not Found**: Application not found, no active scan, or user doesn't have access

> 👥 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.
> 🧾 Audited
> This is recorded as `SCAN_ERRORED` [User Activity](https://apidocs.stackhawk.com/reference/listauditactivity#user-activity-types).


> Requires `write:scan` permission.

## Path parameters

- `appId` string, uuid, required

## Request body

- PerchPerchCommandRequest
  - `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
  - `id` string
  - `name` string

## Response `200`

OK

- PerchPerchCommandResponse
  - `id` string
  - `name` string
  - `status` 'OFFLINE' | 'ONLINE' | 'RUNNING' | 'HEARTBEAT' | 'HOSTED_SCANNER_CONNECTED' | 'HOSTED_SCANNER_PROVISIONING' | 'HOSTED_SCANNER_DISCONNECTED' | 'HOSTED_SCANNER_ERRORED' | 'SCREENR_STARTING' | 'SCREENR_BROWSER_READY' | 'SCREENR_MCP_READY' | 'SCREENR_READY' | 'SCREENR_ANALYZING' | 'SCREENR_SESSION_COMPLETE' | 'SCREENR_CONNECTED' | 'CONFIG_VALIDATOR_CONNECTED' | 'CONFIG_VALIDATION_RUNNING' | 'CONFIG_VALIDATION_COMPLETE' | 'CONFIG_VALIDATION_FAILED' | 'AUTH_VALIDATOR_CONNECTED' | 'AUTH_VALIDATION_RUNNING' | 'AUTH_VALIDATION_COMPLETE' | 'AUTH_VALIDATION_FAILED' | 'SCREENR_SESSION_ABANDONED' | 'SCREENR_SESSION_COMPLETED' | 'VALIDATOR_CONNECTED' | 'SCREENR_ASSET_NOT_FOUND' | 'HOSTED_VALIDATOR_PROVISIONING' | 'SCREENR_AUTH_LOGGED_IN' | 'SCREENR_AUTH_LOGIN_TIMEOUT' | 'SCREENR_AUTH_CONFIG_COMPLETE' | 'SCREENR_AUTH_CONFIG_FAILED' | 'SCREENR_AUTH_READY'

## Other responses

- `400` — Bad Request
- `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)